NAV

API REFERENCE

Authentication Docs

Getting Started

SAP Concur's new Oauth2 framework is a very simple way to implement a Unified Token Authentication mechanism within your application. Here is a four step guide to helping you get up to speed and making calls to SAP Concur's API.

Note: The Pre-2017 Authorization (Deprecated) documentation can be found here

Obtain clientID and clientSecret

Before you can obtain an accessToken, you need to register an application with SAP Concur. You can do this by contacting your Partner Enablement Manager or Partner Account Manager. Once you have registered an application, you will receive a clientId, clientSecret and geolocation. The clientId is a unique UUID4 identifier for your application, and the clientSecret is your application's password. You will be using this credential to obtain tokens either for the application itself, or on behalf of a user. The geolocation is your default base URI for initiating all new connections.

Obtaining an Access Token

In order for an application to call a SAP Concur API, you need to obtain an accessToken on behalf of either a User, Company or Application. There are multiple ways of obtaining an accessToken through the various grants (Password, Authorization, Client Credentials, One-time Password) .

This section provides a quick start guide for generating an access token. If you are developing an application to be certified for the App Center or as a TripLink supplier, please refer to the certification documentation for the grant types your application must support.

For simplicity, we will use the Password grant flow as an example. The Password grant flow is used when you need to authenticate a user, using its username and password. This is typically reserved from SAP Concur applications (i.e. where the user's credentials will be captured and stored) but is used here for demonstration purposes.

When making the call, you will use your app's geolocation as the base URI followed by the endpoint. For example, if your geolocation is https://us.api.concursolutions.com, you will call https://us.api.concursolutions.com/oauth2/v0/token.

The first time you request for an accessToken a refreshToken is also returned. There are certain conditions where a refreshToken is not returned. This is used to get a new accessToken when one has expired. (see below for more info)

Example shell script using cURL to obtain an accessToken:

oauth2_base=https://us.api.concursolutions.com/oauth2
username=<concur_username> eg. john.doe@gmail.com
password=<password> eg. password1
client_id=<clientId> eg. e01f725d-b4ce-4ce3-a664-b670cb5876cb0
client_secret=<clientSecret> eg. 35c3bd92-fcb8-405e-a886-47ff3fba5664
curl -X POST -H 'concur-correlationid: nameofapp' "$oauth2_base/v0/token" --data "username=$username&password=$password&grant_type=password&client_secret=$client_secret&client_id=$client_id"

Full docs: https://developer.concur.com/slate-ui/build/api-reference.html#password-grant

Store the token and geolocation.

Calling an API with Access Token

Once you have the accessToken, you need to supply this in an Authorization header in the form of Authorization: Bearer <accessToken> when making a HTTPS call. The accessToken is a large string that looks something like this:

eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6IjE0NTU2MTQzNDYifQ.eyJhdWQiOiIqIiwic3ViIjoiaHR0cDovL21zcGNzcHJzcnFhLmNvbmN1ci5jb25jdXJ0ZWNoLm9yZzozMDAzL3Byb2ZpbGUtc2VydmljZS92MS91c2Vycy83NjAwOUFEMy1GNzdCLTREOTgtQTIxQS01NTNDOUM5MTc5RjAiLCJpc3MiOiJodHRwczovL2NvbmN1ci5jb20iLCJleHAiOjE0NzM4OTUxMjksImxlZ2FjeV9hcHBsaWNhdGlvbl9pZCI6MTUwMDA2MzY1OSwidXNlclVSSSI6Imh0dHA6Ly9tc3Bjc3Byc3JxYS5jb25jdXIuY29uY3VydGVjaC5vcmc6MzAwMy9wcm9maWxlLXNlcnZpY2UvdjEvdXNlcnMvNzYwMDlBRDMtRjc3Qi00RDk4LUEyMUEtNTUzQzlDOTE3OUYwIiwidXNlcnV1aWQiOiI3NjAwOUFEMy1GNzdCLTREOTgtQTIxQS01NTNDOUM5MTc5RjAiLCJuYmYiOjE0NzM4OTE1MjksImh0dHBzOi8vYXBpLmNvbmN1cnNvbHV0aW9ucy5jb20vYXBwIjoiaHR0cHM6Ly9hcGkuY29uY3Vyc29sdXRpb25zLmNvbS9hcHAtbWdtdC92MC9hcHBzL2UwMTBlMjVkLWI0Y2UtNGNlMy1hN2U0LWI2NzBjYjFhZGNiMCIsImh0dHBzOi8vYXBpLmNvbmN1cnNvbHV0aW9ucy5jb20vc2NvcGVzIjpbIkNDQVJEIiwiQ09NUEQiLCJVU0VSIiwidXNlcl9yZWFkIiwiRU1FUkciLCJKT0JMT0ciLCJFUkVDUFQiLCJJVElORVIiLCJGSVNWQyIsIkxJU1QiLCJQQVNTViIsIkNPTkZJRyIsIkZPUCIsIkdIT1NUIiwiQ09OUkVRIiwiVFJJUElUIiwiQ09NUEFOWSIsInByb2ZpbGUiLCJFVlMiLCJlbWFpbCIsIlRSVlBUUyIsIkFUVEVORCIsIklOVlBPIiwiTk9USUYiLCJUUlZSRVEiLCJTVVBTVkMiLCJFWFBSUFQiLCJhZGRyZXNzIiwiRVhUUkNUIiwiUEFZQkFUIiwid3Jvbmdfc2NvcGUiLCJJTlZQTVQiLCJJTUFHRSIsIlRBWElOViIsIlJDVElNRyIsIlVOVVRYIiwiVFdTIiwiVE1DU1AiLCJCQU5LIiwiSU5WVkVOIiwib3BlbmlkIiwiTVRORyIsIklOU0dIVCIsIlRSVlBSRiIsIklOVlRWIiwiTUVESUMiLCJUU0FJIl0sImlhdCI6MTQ3Mzg5MTUyOX0.QHY4Mc5A3J981-HDv7KUdgS4tUI-qnmQAxwe9J6DHxuMmYSoGEYZ0dsnLnqc2lO2iVJK6Pg3EBZTArq8_vzV2FK7tA4-IT1eCEHo1e-RWZyWLnR7P56SvZozXpY73daovSH7572HrUm21FXcyLmdaLZyo2LfFcChaghbSCjm1Jg1duH-pLPUW4d89-_pdakmyxfV3GCm2N_XQXoRhNYAAiZcG8UfxEn3TpMHJ96F2n6keJanT_Sn2Sek_sH2EmeeCpg5-jDe0fvLvr1-gY5t0ifq8QBKWHSUUIrGbQvseD6CGzfyiFUqVypN2lukfWACR-26otN50c0OzY6kgY06RA

When you receive the accessToken, store it with the token's geolocation. That geolocation will be the base URI for all subsequent calls.

Armed with the accessToken you can start making calls to SAP Concur's API. Here's an example to retrieve profile information for a User in the Production environment using cURL (utilize the appropriate base URI geolocation for the token). Base URIs Reference:

curl -k -v -H "Accept: application/json" \
-H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6IjE0NTU2MTQzNDYifQ.eyJhdWQiOiIqIiwic3ViIjoiaHR0cDovL21zcGNzcHJzcnFhLmNvbmN1ci5jb25jdXJ0ZWNoLm9yZzozMDAzL3Byb2ZpbGUtc2VydmljZS92MS91c2Vycy83NjAwOUFEMy1GNzdCLTREOTgtQTIxQS01NTNDOUM5MTc5RjAiLCJpc3MiOiJodHRwczovL2NvbmN1ci5jb20iLCJleHAiOjE0NzM4OTUxMjksImxlZ2FjeV9hcHBsaWNhdGlvbl9pZCI6MTUwMDA2MzY1OSwidXNlclVSSSI6Imh0dHA6Ly9tc3Bjc3Byc3JxYS5jb25jdXIuY29uY3VydGVjaC5vcmc6MzAwMy9wcm9maWxlLXNlcnZpY2UvdjEvdXNlcnMvNzYwMDlBRDMtRjc3Qi00RDk4LUEyMUEtNTUzQzlDOTE3OUYwIiwidXNlcnV1aWQiOiI3NjAwOUFEMy1GNzdCLTREOTgtQTIxQS01NTNDOUM5MTc5RjAiLCJuYmYiOjE0NzM4OTE1MjksImh0dHBzOi8vYXBpLmNvbmN1cnNvbHV0aW9ucy5jb20vYXBwIjoiaHR0cHM6Ly9hcGkuY29uY3Vyc29sdXRpb25zLmNvbS9hcHAtbWdtdC92MC9hcHBzL2UwMTBlMjVkLWI0Y2UtNGNlMy1hN2U0LWI2NzBjYjFhZGNiMCIsImh0dHBzOi8vYXBpLmNvbmN1cnNvbHV0aW9ucy5jb20vc2NvcGVzIjpbIkNDQVJEIiwiQ09NUEQiLCJVU0VSIiwidXNlcl9yZWFkIiwiRU1FUkciLCJKT0JMT0ciLCJFUkVDUFQiLCJJVElORVIiLCJGSVNWQyIsIkxJU1QiLCJQQVNTViIsIkNPTkZJRyIsIkZPUCIsIkdIT1NUIiwiQ09OUkVRIiwiVFJJUElUIiwiQ09NUEFOWSIsInByb2ZpbGUiLCJFVlMiLCJlbWFpbCIsIlRSVlBUUyIsIkFUVEVORCIsIklOVlBPIiwiTk9USUYiLCJUUlZSRVEiLCJTVVBTVkMiLCJFWFBSUFQiLCJhZGRyZXNzIiwiRVhUUkNUIiwiUEFZQkFUIiwid3Jvbmdfc2NvcGUiLCJJTlZQTVQiLCJJTUFHRSIsIlRBWElOViIsIlJDVElNRyIsIlVOVVRYIiwiVFdTIiwiVE1DU1AiLCJCQU5LIiwiSU5WVkVOIiwib3BlbmlkIiwiTVRORyIsIklOU0dIVCIsIlRSVlBSRiIsIklOVlRWIiwiTUVESUMiLCJUU0FJIl0sImlhdCI6MTQ3Mzg5MTUyOX0.QHY4Mc5A3J981-HDv7KUdgS4tUI-qnmQAxwe9J6DHxuMmYSoGEYZ0dsnLnqc2lO2iVJK6Pg3EBZTArq8_vzV2FK7tA4-IT1eCEHo1e-RWZyWLnR7P56SvZozXpY73daovSH7572HrUm21FXcyLmdaLZyo2LfFcChaghbSCjm1Jg1duH-pLPUW4d89-_pdakmyxfV3GCm2N_XQXoRhNYAAiZcG8UfxEn3TpMHJ96F2n6keJanT_Sn2Sek_sH2EmeeCpg5-jDe0fvLvr1-gY5t0ifq8QBKWHSUUIrGbQvseD6CGzfyiFUqVypN2lukfWACR-26otN50c0OzY6kgY06RA" \
https://us.api.concursolutions.com/profile/v1/me

and the response will look like:

{
  "addresses": [
    {
      "type": "Home",
      "streetAddress": "",
      "locality": "",
      "region": "",
      "postalCode": "",
      "country": "US"
    },
    {
      "type": "Work",
      "streetAddress": "",
      "locality": "",
      "region": "",
      "postalCode": "",
      "country": "US"
    }
  ],
  "travelIds": {
    "userId": 85663431,
    "companyId": "63E447F6-A6A7-4B70-A951-10F45d693B43",
    "companyInternalId": 222458,
    "setId": 91157361,
    "ruleClassId": 394103,
    "travelConfigId": 0
  },
  "meta": {
    "created": "2016-06-08T00:00:00.000",
    "lastModified": "2016-08-22T14:32:00.000",
    "resourceType": "EnterpriseUser"
  },
  "displayName": "Brown",
  "name": {
    "formatted": "Brown, Terry ",
    "familyName": "Brown",
    "givenName": "Terry",
    "middleName": "",
    "honorificPrefix": "",
    "honorificSuffix": ""
  },
  "phoneNumbers": [
    {
      "type": "Home",
      "value": "tel:+1-4251231244",
      "primary": false,
      "notifications": false,
      "countryCode": "US",
      "countryISDCode": "1"
    },
    {
      "type": "Work",
      "value": "tel:+1-4251231234;ext=",
      "primary": false,
      "notifications": false,
      "countryCode": "US",
      "countryISDCode": "1"
    }
  ],
  "com:concur:Employee:1.0": {
    "employeeId": "brown@brown-sandbox.com",
    "jobTitle": "",
    "managerId": null,
    "orgUnitId": null
  },
  "dateOfBirth": null,
  "schemas": [
    "com:concur:User:1.0",
    "com:concur:Employee:1.0"
  ],
  "active": true,
  "id": "e01f725d-b4ce-4ce3-a664-b670cb5876cb0",
  "com:concur:TravelPreferences:1.0": {
    "air": {
      "seat": {
        "interrowPosition": null,
        "sectionPosition": null
      },
      "meal": "DontCare",
      "homeAirport": null
    },
    "rail": {
      "space": "DontCare",
      "meal": "DontCare",
      "bedCategory": "DontCare",
      "fareSpaceComfort": "DontCare",
      "deck": "DontCare",
      "coach": "DontCare",
      "bed": "DontCare",
      "berth": "DontCare",
      "noiseComfort": "DontCare",
      "contingency": "DontCare",
      "seat": "DontCare"
    },
    "car": {
      "smoking": "DontCare",
      "carType": "DontCare",
      "transmission": "DontCare",
      "gpsEnabled": false,
      "skirack": false
    },
    "hotel": {
      "earlyCheckin": false,
      "remark": null,
      "pool": false,
      "roomService": false,
      "foamPillows": false,
      "accessForBlind": false,
      "accessForWheelchair": false,
      "gym": false,
      "roomType": "DontCare",
      "restaurant": false,
      "rollawayBed": false,
      "smoking": "DontCare",
      "crib": false
    }
  },
  "gender": null,
  "emails": [
    {
      "value": "brown@brown-sandbox.com",
      "type": "Business",
      "notifications": true
    }
  ],
  "userType": "Enterprise"
}

Full docs: https://developer.concur.com/slate-ui/build/api-reference/user/

Access Token Expiry and Obtaining a Fresh One

Access Tokens have a default One hour lifetime. In order to obtain a fresh accessToken you need to call the auth endpoint using the Refresh Grant. This will return a brand new accessToken and a refreshToken. Refresh Tokens have a default 6 month lifetime. Clients will typically store the refreshToken together with the other user metadata like login information and unique identifiers.

Utilizing the geolocation for the token, here's an example of a cURL call to obtain a new accessToken

curl -X POST 'https://us.api.concursolutions.com/oauth2/v0/token' --data "client_id=$client_id&client_secret=$client_secret&grant_type=refresh_token&refresh_token=<old refresh token>"

Full docs: https://developer.concur.com/slate-ui/build/api-reference/authentication/apidoc.html#refresh_token

Now that you've made your first call, read up more about SAP Concur's wide ranging APIs and how they can enhance your application or solve your business needs.

ref: https://developer.concur.com/slate-ui/build/api-reference/index.html

Authentication

Special Note: (Please Read First)

If you are an existing partner with an existing app, please read both the Migration to Oauth2 Tokens and Getting Started documentation first. If you have any questions, please contact your Partner Enablement team representative before proceeding.

Note: The Pre-2017 Authorization (Deprecated) documentation be found here

Access Tokens

The Oauth2 service generates access tokens for authenticated users, applications or companies. The token returned in the Oauth2 response can be used to access protected resources on SAP Concur services.

The Oauth2 response can, depending on grant type contain these values:

Name Type Format Description
expires_in string - The lifetime in seconds of the access token
scope string - The scope of the access token as granted to the client application
token_type string - The type of token returned. Value will be Bearer
access_token string - Token used to access protected resources of SAP Concur services.
refresh_token string - Refresh token required to request a new access token for a given user.
geolocation string - The base URL for where the user profile lives. See base URI for usage.
id_token string - The OCID Token in the JSON Web Token (JWT) format that describes the user or company

Token Response

HTTP/1.1 200 OK
Content-Type: application/json
Date: date-requested
Content-Length: 3397
Connection: Close
{
  "expires_in": "3600",
  "scope": "app-scopes",
  "token_type": "Bearer",
  "access_token": "access_token",
  "refresh_token": "refresh_token",
  "id_token": "ocid_token",
  "geolocation": "https://us.api.concursolutions.com"
}

Obtaining a token

You can obtain a token for three different types of principals in the SAP Concur universe.

Token Lifetime

An accessToken has a one hour lifetime.

In order to obtain a token, the client application needs to call the Oauth2 endpoint using various grants depending on the authentication scenarios required. The full list of supported scenarios is provided below:

Refreshing a token

The refresh grant is used to refresh an access_token that has expired. This grant can be used anytime a refresh_token is returned in the response of another grant request. No user interaction is required.

Token Lifetime

A refresh token has a six month lifetime. If the refresh token expires, the client application must reinitiate the authorization process. When a refresh token is used to request a new access token, both a new access token as well as a new refresh token are returned in the response. This token can change even if most of the time, this value is the same. Client applications should treat all returned refresh tokens as new tokens and overwrite the stored tokens with the new token from the response.

It is recommended that the client application use the refresh grant to request a new access token as the initial step of accessing protected resources of SAP Concur services.

Refreshing the token

To request a new access token using a valid refresh token, use the Oauth2 /token endpoint. Use the application/x-www-form-urlencoded content type.

POST /oauth2/v0/token

Post Body

Name Type Format Description
client_id string UUID Required The client applications client_id supplied by App Management
client_secret string UUID Required The client applications client_secret supplied by App Management
refresh_token string UUID Required An existing valid refresh token to be used to request a new access token
scope string - Optional The client applications list of scopes
grant_type string - Required The grant type instructs the Oauth2 service how to process the request. For refresh token, the value must be refresh_token

Request

POST /oauth2/v0/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: us.api.concursolutions.com
Connection: close
Content-Length: 437

POST BODY
client_id=your-client_id
&client_secret=your-client_secret
&grant_type=refresh_token
&refresh_token=valid-refresh_token
&scope=app-scope

Response

HTTP/1.1 200 OK
Content-Type: application/json
Date: date-requested
Content-Length: 3397
Connection: Close
{
  "expires_in": "3600",
  "scope": "app-scopes",
  "token_type": "Bearer",
  "access_token": "access_token",
  "refresh_token": "refresh_token",
  "id_token": "ocid_token",
  "geolocation": "https://us.api.concursolutions.com"
}

Revoking a token

All refresh_tokens associated to a user for an application can be revoked by calling the https://us.api.concursolutions.com/app-mgmt/v0/connections endpoint with a DELETE action. You have to provide the User's accessToken in the Authorization Header as Authorization: Bearer <access_token>.

DELETE https://us.api.concursolutions.com/app-mgmt/v0/connections

Request

DELETE https://us.api.concursolutions.com/app-mgmt/v0/connections
Authorization: Bearer {token}

Response

HTTP/1.1 200 OK

Managing tokens

Refresh Tokens are UUID4 identifiers that allow your application to obtain a fresh accessToken on behalf of a user to access SAP Concur APIs.

e013335d-b4ce-4c43-a7e4-b67abc1adcb0

It is highly recommended that you store Refresh Tokens together with your user's authorization metadata in your application every time you obtain a new refreshToken as they might change depending on different scenarios.

FOR APP CENTER AND SUPPLIER PARTNERS supporting all geolocations, storing the authorization metadata, including the geolocation are REQUIRED.

Base URIs

When making API calls, the appropriate base URI should be used. There are three different scenarios: 1. Obtaining a token for a user. 2. Refreshing a token. 3. Calling other APIs.

The base URI for obtaining a token will leverage your application's geolocation. The base URI for refreshing tokens and all other API calls will leverage the token's geolocation.

Base URIs for Obtaining a Token

When your application is created, you will be provided with a client ID, secret and geolocation. When obtaining a token, your application should use the base URI for the geolocation in which your application exists.

There are two endpoints for each geolocation - one is the default (used for server-side calls) and the other should be used for client-side calls.

The full list of available token geolocations is available on the Base URIs page.

When obtaining the token, the token's geolocation will be included in the response. The token's geolocation should be stored along with the token. The Developer's app will then be able to make subsequent calls using the token and the correct end points based on the token's GEO location.

Base URIs for All Other Calls

When refreshing a token or when calling any other APIs, the token's geolocation should be used as the base URI.

Note: Client-side calls should use the www- variant of the base URI.

For example: When obtaining a token, if the response was the below:

HTTP/1.1 200 OK
Content-Type: application/json
Date: date-requested
Content-Length: 3397
Connection: Close
{
  "expires_in": "3600",
  "scope": "app-scopes",
  "token_type": "Bearer",
  "access_token": "access_token",
  "refresh_token": "refresh_token",
  "id_token": "ocid_token",
  "geolocation": "https://us.api.concursolutions.com"
}

When then calling the receipts API to post a receipt, your request should be made to https://us.api.concursolutions.com (if server side) or https://www-us.api.concursolutions.com (for clients).

ID Token

Authentication service will return an OPENID compatible ID token with every token request. This id_token is primarily used to describe information about a user or a company. You can obtain the userId from this token.

Sample id_token:

{
  "aud": "e010e25d-b4ce-4ce3-a7e4-b670cb1adcb0",
  "concur.profile": "https://us.api.concursolutions.com/profile/v1/principals/76459ad3-f77b-4d98-a21a-55333c9179f0",
  "concur.version": 2,
  "concur.type": "user",
  "sub": "76459ad3-f77b-4d98-a21a-55333c9179f0",
  "iss": "https://us.api.concursolutions.com",
  "exp": 1485485529,
  "nbf": 1485481929,
  "at_hash": "351515a6482f4ee1",
  "iat": 1485481929
}

Verifying an id_token

The Authentication service exposes JWKs that can be used to validate the id_token in the form of a JWT. Validating a JWT is described in detail in RFC 7519 - sec 7.2

This is the link to the SAP Concur JSON Web Key for Oauth2. https://www-us.api.concursolutions.com/oauth2/v0/jwks

Authorization grant

The authorization grant is the regular 3-legged oauth2 grant and is defined in detail in RFC6749 sec-4.1. This grant requires the user to explicitly authenticate themselves and authorise the application initiating the grant.

The users must be able to authenticate themselves via an SAP Concur username & password. Users will be challenged to login by an Oauth2 HTML page.

Who should use it * 3rd party "partner" websites - or - * non-SAP Concur Applications - & - * Applications that need explicit user authentication & authorization - & - * Applications that can securely store a code, access_token & refresh_token

Grant details

Note that the grant type must be accessed using the www- version of the API Gateway in order to avoid certificate issues with some browsers. (ex: https://www-us.api.concursolutions.com instead of https://us.api.concursolutions.com)

GET /oauth2/v0/authorize

Name Type Format Description
client_id string UUID Applications client_id supplied by App Management
redirect_uri string - The redirect URI for your application to continue with the Oauth2 flow
scope string - List of scopes that application is asking for
response_type string - code
state string -

With this grant, the user has two authentication options: 1. Username and password 2. One-time link using a verified email address

With both options, once the user is successfully authenticated and the user authorizes your application, the user will be redirected to the redirect_URI specified in the initial /authorize call with a temporary token appended.

<redirect_uri>?geolocation=<token_geolocation>&code=<token>

If the user is not successfully authenticated or does not authorize the scopes for your application, an error code and description will be appended to the redirect URI. Please refer to the Response Codes section for more information.

Your application must then exchange the temporary token for a long-lived token using the below.

POST /oauth2/v0/token

Name Type Format Description
client_id string UUID Applications client_id supplied by App Management
client_secret string UUID Applications client_secret supplied by App Management
redirect_uri string - The redirect_uri that is registered for the application
code string UUID The authorization code provided by Auth
grant_type string - authorization_code

Password grant

The Password grant can be used when there is a trust relationship between the user and the application. There are two credential types allowed with Password Grant:

  1. "Password": with this credential type, the application either already has the user's credentials or can obtain the user's credentials by directly interacting with the user.
  2. "AuthToken": This credential type is used for connections from the App Center. For App Center partners and TripLink suppliers, please refer to the certification documentation for more information.

Post Body

Name Type Format Description
client_id string UUID Applications client_id supplied by App Management
client_secret string UUID Applications client_secret supplied by App Management
grant_type string - Specify which grant type you expect the oauth2 service to process. for password grant, the value is password
username string - specify the username or userId
password string - specify the user's password
credtype string - The credtype signifies to oauth2 which credential set is being submitted in the request. There are two supported values: authtoken and password. For connections from the App Center, use authtoken. if omitted, oauth2 will assume the type is password.

Request

POST /oauth2/v0/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: us.api.concursolutions.com
Connection: close
Content-Length: 175

POST BODY
client_id=your-client_id
&client_secret=your-client_secret
&grant_type=password
&username=username
&password=password

Response

HTTP/1.1 200 OK
Content-Type: application/json
Date: date-requested
Content-Length: 3397
Connection: Close
{
  "expires_in": "3600",
  "scope": "app-scopes",
  "token_type": "Bearer",
  "access_token": "access_token",
  "refresh_token": "refresh_token",
  "id_token": "ocid_token",
  "geolocation": "https://us.api.concursolutions.com"
}

example bad login

{
  "error": "invalid_grant",
  "error_description": "Incorrect Credentials. Please Retry",
  "code": 5
}

Client Credentials grant

Use the application/x-www-form-urlencoded content type.

POST /oauth2/v0/token

Post Body

Name Type Format Description
client_id string UUID Required Applications client_id supplied by App Management
client_secret string UUID Required Applications client_secret supplied by App Management
grant_type string - Required Specify which grant type you expect the oauth2 service to process. For client_credentials grant, the value is client_credentials

Request

POST /oauth2/v0/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: us.api.concursolutions.com
Connection: close
Content-Length: 127

POST BODY
client_id=your-client_id
&client_secret=your-client_secret
&grant_type=client_credentials

Response

HTTP/1.1 200 OK
Content-Type: application/json
Date: date-requested
Content-Length: 1626
Connection: Close
{
  "expires_in": "3600",
  "scope": "app-scopes",
  "token_type": "Bearer",
  "access_token": "access_token",
  "geolocation": "https://us.api.concursolutions.com"
}

One Time Password grant

The One-time Password grant type leverages email, phone (text messaging), instant messaging and similar systems to provide per user access tokens to client applications. This grant type requires the following steps:

  1. The calling application calls the OAuth2 service specifying the otp grant type along with required parameters.
  2. The OAuth2 service generates a one time token which it sends through the messaging mechanism chosen by the application.
  3. The user retrieves the token and presents it to the application. The means of having this presented to the application is the responsibility of the application.
  4. The application presents this one-time token to the OAuth2 service via the token endpoint.

Request a one-time token to be sent to the user

Use the application/x-www-form-urlencoded content type.

POST /oauth2/v0/otp

Post Body

Name Type Format Description
client_id string UUID Required The client_id as defined in the SAP Concur application management system.
client_secret string UUID Required The client_secret as set by the client owner in the SAP Concur application management system.
channel_handle string - Required The location (email address, phone number) where the one time token should be sent. Currently, only email address is valid.
channel_type string - Required The type of messaging system to use. Currently only email is valid
name string - Optional The name of the user that appears in the email.
company string - Optional The company or application name that appears in the email.
link string - Optional The callback URL that appears in the email for users to click to complete the auth flow.

The calling application code can also append n-number of unique client defined parameters in the URI for the purpose of connecting the one time token to the application when received by the user. The names of these parameters cannot conflict with the API defined parameters.

The following are reserved words and cannot be used as client application defined parameters:

/otp: "client_id" "client_secret" "channel_type" "channel_handle"
/token: "client_id" "client_secret" "channel_type" "channel_handle" "scope" "grant_type" "otp"

If the calling application chooses to send custom parameters, all of these exact same parameters must be included in subsequent API calls to acquire the access token. In other words, the URI signature, modulo the one time token parameter itself and token service specific parameters, must match the originating URI signature.

Request

POST /oauth2/v0/otp HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Accept: application/json
Host: us.api.concursolutions.com
Connection: close
Content-Length: 437

POST BODY
client_id=your-client_id
&client_secret=your-client_secret
&channel_handle=email adress
&channel_type=valid-email
&link=https://example.com/callback

Response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 22
Date: date-requested
{
  "message": "otp sent"
}

Request an access token

The One Time Password grant requires that all of the parameters, including client application defined parameters to be sent in the request body when requesting an access token. Use the application/x-www-form-urlencoded content type.

POST oauth2/v0/token

Post Body

Name Type Format Description
client_id string UUID Required The client_id as defined in the SAP Concur application management system.
client_secret string UUID Required The client_secret as set by the client owner in the SAP Concur application management system.
channel_handle string - Required The location (email address, phone number) where the one time token should be sent.
channel_type string - Required The type of messaging system to use. Currently only email is valid
scope string - The scope(s) requested by the client for the token.
grant_type string - Required The grant type being used, specifically for this approach: otp.
otp string - Required The one-time token provided as a result of the Send a one time token to the user method.

Request

POST /oauth2/v0/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: us.api.concursolutions.com
Connection: close
Content-Length: 437

POST BODY
client_id=your-client_id
&client_secret=your-client_secret
&channel_handle=email adress
&channel_type=valid-email
&scope=app_scope
&grant_type=otp
&otp=one-time-token

Response

HTTP/1.1 200 OK
Date: date-requested
Content-Length: 1490
Connection: keep-alive
{
  "expires_in": "3600",
  "scope": "app-scopes",
  "token_type": "Bearer",
  "access_token": "access_token",
  "refresh_token": "refresh_token",
  "id_token": "ocid_token",
  "geolocation": "https://us.api.concursolutions.com"
}

Response Codes

HTTP Status returned by oauth2

HTTP Status Description
200 OK - Successful call, response is in body.
400 Bad Request (error, error_description, code)
401 Unauthorized (error, error_description, code)
403 Forbidden (error, error_description, code)
404 Not Found (error, error_description, code)
500 Server Error, error message is in body.
503 Server Timed Out, error message is in body.

4xx class errors have a JSON response with the following fields

{
  "code": <number>,
  "error": <error>,
  "error_description": <error_description>,
  "geolocation": <geolocation url where user lives>
}

/authorize

If the authorization or authentication are unsuccessful, your application will receive an error code and description at the redirect_uri provided.

 error_code=<>
 &error_description=<>

In all cases, the friendly error description should be displayed to the user.

/token

Code Error Description
5 invalid_grant Incorrect credentials. Please Retry
10 invalid_grant Account is disabled. Please contact support
11 invalid_grant Account is disabled. Please contact support
12 invalid_grant Logon Denied. Please contact support
13 invalid_grant Logon Denied. Please contact support
14 invalid_grant Account Locked. Please contact support
16 invalid_request user lives elsewhere
19 invalid_grant Incorrect credentials. Please Retry
20 invalid_grant Logon Denied. Please contact support (typically due to IP restriction)
51 invalid_request username was not supplied
52 invalid_request password was not supplied
53 invalid_client company is not enabled for this client
54 invalid_scope requested scope exceeds granted scope
55 invalid_request we don't know this email
56 invalid_request otp was not supplied
57 invalid_request channel_type missing
58 invalid_request channel_handle missing
59 access_denied client disabled
60 invalid_grant these are not the grants you are looking for
61 invalid_client client not found
62 invalid_request client_id was not supplied
63 invalid_request client_secret was not supplied
64 invalid_client Incorrect credentials. Please Retry
65 invalid_request grant_type was not supplied
80 invalid_request invalid channel type
81 invalid_request bad channel handle
83 invalid_request otp not found
84 invalid_request fact verification failed
85 invalid_request otp verification failed
100 invalid_request backend does not know about this username
101 invalid_request code was not supplied
102 invalid_request redirect_uri was not supplied
103 invalid_request code is bad or expired
104 invalid_grant redirect_uri does not match the previous grant
105 invalid_grant this grant was not issued to you!
106 invalid_request refresh_token was not supplied
107 invalid_request refresh disallowed for app
108 invalid_grant bad or expired refresh token
109 invalid_request loginid was not supplied
115 invalid_request unauthenticated client will not be issued token!
117 invalid_request nonce is mandatory for this response_type
118 invalid_request display is invalid
119 invalid_request prompt is invalid
119 invalid_request prompt must be set to consent for offline_access
120 invalid_request credtype is invalid
121 invalid_request login_type is invalid
122 invalid_request proxies supplied are invalid
123 invalid_request principal is disabled

/otp

Code Error Description
16 invalid_request user lives elsewhere
57 invalid_request channel_type was not supplied
58 invalid_request channel_handle was not supplied
60 invalid_grant these are not the grants you are looking for
61 invalid_client client_id is not known to us
62 invalid_request client_id was not supplied
63 invalid_request client_secret was not supplied
80 invalid_request invalid channel type
81 invalid_request bad channel handle
82 invalid_request the number of open otp requests has been exceeded

Troubleshooting

In order to assist with troubleshooting, SAP Concur responds with a unique correlationId in the response header. The key to look for is correlationid. This unique code can be used during troubleshooting as it identifies the API call in the log files. You should record this information in your own API call logs as well so that you can pass this information on to the SAP Concur support team.

Example of the correlationid in the response:

< HTTP/1.1 200 OK
< Server: cnqr-papeete
< Date: Mon, 04 Dec 2017 22:07:05 GMT
< Content-Type: application/json
< Content-Length: 2897
< Connection: keep-alive
< Concur-Correlationid: 2803b8f8-a42b-43c2-a739-b8768e4759b8

Enterprise Business Applications

Only the Password Grant Type is available for obtaining company-level tokens.

  1. To begin the authentication flow, a Customer's SAP Concur Administrator clicks on the Connect button within the App Center listing and authorizes the partner's app. This app listing is located within customer's SAP Concur system's App Center tab.
  2. The SAP Concur authorization service will redirect the Admin to the Partner’s Landing Page. Partners should follow the App Center UX Guidelines to create a web page that listens for an HTTP GET request from SAP Concur.
  3. The redirect URI will contain an id, requestToken and userId parameters. Example: https://{partner_redirect_URI}?id=8568a4cd-8ffc-49d6-9417-be2d69aa075f&requestToken=5l85ae5a-426f-4d6f-8af4-08648c4b696b&userId=9bdded51-00b8-4f84-8bef-6d3afe727007
  4. When the Partner application receives the redirect call, the Partner should strip the id and requestToken values from the URI and use those on a Post request to the SAP Concur Authorization service to obtain the official Oauth2 Access Token and Refresh Token for the customer using the password grant. As explained in detail in this presentation, the Partner must have Data Center Geo Awareness related to the token. We currently have 3 Data Centers and the API end points change based on these Data Centers so it is imperative the proper token management is followed. Otherwise, your app will not make the correct call per Access token.
  5. An access token is valid for only one hour. The access token should be cached in memory and discarded after use.
  6. After the Admin has successfully completed the login/enrollment process, the Partner should store the following elements with the customer’s profile metadata.
    • refresh_token: (36 characters including dashes) Valid for six months from the day and time issued.
    • refresh_expires_in: This is Epoch time format, convert to UTC.
    • geolocation: To be used when making API calls on behalf of the customer.
    • id: Aka sub, is the customer’s unique identifier (UUID). It can be retrieved from the following sources:
    • From the re-direct URI as the id element.
    • By decoding the id_token returned with Access token, as the sub element. (See https://jwt.io)
  7. It is highly recommended that Partners log the following elements:
    • userId: the user who clicked on the Connect button (returned in the re-direct URI)
    • correlationid: SAP Concur responds with a unique code which identifies the API call in the log files. (returned in the response header). More details can be found here.

Company Level Authentication

Company

Company is a top-level principal within Concur and you would be able to obtain an access token and a refresh token on a Company's behalf just like you would be able to with a User. Only one authorization flow is currently available for obtaining tokens for a Company, which is the Password grant using a temporary auth token received from the App Center.

Obtaining A One-Time Auth Token

To begin the authentication flow for a company, one must first obtain a temporary auth token through AppCenter's interface. AppCenter will request for a temporary auth token and hand it off to the partner, who will then in turn use Password grant to exchange the temporary auth token for a full access token and refresh token for the company.

Auth tokens are valid only for 12 hours. Partners have 12 hours to exchange the auth token for a refresh and access token, and can use this auth token multiple times within the 12 hours in case of network failure.

This auth flow diagram describes this handshake:

Company Authentication Flow Sequence Diagram

Company Authentication Flow Sequence Diagram

AppCenter will call this endpoint to obtain an authToken. (on right)

AppCenter will call this endpoint to obtain an authToken:

(HTTP)

POST /profile-service/v1/keys/principals/<companyId>/authtoken/

Sample Curl: (on right) ```shell

(CURL)

curl -E appcenter.p12:. -H 'concur-correlationid: githbuwiki' -XPOST https://us.api.concursolutions.com/profile-service/v1/keys/principals/08BCCA1E-0D4F-4261-9F1B-F778D96617D6/authtoken/



```shell
200 OK
{
  "status": "PASS",
  "code": 0,
  "errormsg": "",
  "token": "<authToken>"
}

AppCenter redirects User to Client's auth handler URI (Connect URL) and passing in the authToken

301 Redirect https://client.app.url?id=$company_uuid&requestToken=$request_token&userID=$user_uuid

At this point, the user should be prompted to sign in to your application. If the user doesn't not have account, the user should have the ability to create one. For applications that have user read scope, the User UUID can be used to pre-populate the account creation forms. Please see the App Center User Experience guidelines for more information.

Client app calls Oauth2 password grant to get an access token for the company

Name Type Format Description
client_id string UIID Applications client_id supplied by App Management
client_secret string UUID Applications client_secret supplied by App Management
grant_type string - Specify which grant type you expect the oauth2 service to process. For password grant, the value is password
username string - specify the companyId to be used in the password grant request. The id above.
password string - specify the authToken to be used in the password grant request. The requestToken above.
credtype string - The credtype signifies to oauth2 which credential set is being submitted in the request. The value: authtoken.

See Example Request and Response

Example Request and Response

(Request)

POST /oauth2/v0/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: us.api.concursolutions.com
Connection: close
Content-Length: 175

client_id=your-client_id
&client_secret=your-client_secret
&grant_type=password
&username=<companyId>
&password=<authtoken>
&credtype=authtoken
(RESPONSE: Success)

HTTP/1.1 200 OK
Content-Type: application/json
Date: date-requested
Content-Length: 3397
Connection: Close 
{
  "expires_in": "3600",
  "scope": "app_scopes",
  "token_type": "Bearer",
  "access_token": "access_token",
  "refresh_token": "refresh_token",
  "geolocation":"https://us.api.concursolutions.com"
}
(RESPONSE: Failure)

{
  "error": "invalid_grant",
  "error_description": "Incorrect Credentials. Please Retry",
  "code": 5
}

Company Level Authentication - Response Codes

HTTP Status Code returned by oauth2

HTTP Status Code Description
200 OK - Successful call, response is in body.
400 Bad Request (error, error_description, code)
401 Unauthorized (error, error_description, code)
403 Forbidden (error, error_description, code)
404 Not Found (error, error_description, code)
500 Server Error, error message is in body.
503 Server Timed Out, error message is in body.

4xx class errors have a JSON response with the following fields

{
  "code": "<number>",
  "error": "<error>",
  "error_description": "<error_description>"
}
/token
Code Error Description
5 invalid_grant Incorrect credentials. Please Retry
10 invalid_grant Account is disabled. Please contact support
11 invalid_grant Account is disabled. Please contact support
12 invalid_grant Logon Denied. Please contact support
13 invalid_grant Logon Denied. Please contact support
14 invalid_grant Account Locked. Please contact support
16 invalid_request user lives elsewhere
19 invalid_grant Incorrect credentials. Please Retry
51 invalid_request username was not supplied
52 invalid_request password was not supplied
53 invalid_client company is not enabled for this client
54 invalid_scope requested scope exceeds granted scope
55 invalid_request we don't know this email
56 invalid_request otp was not supplied
57 invalid_request channel_type missing
58 invalid_request channel_handle missing
59 access_denied client disabled
60 invalid_grant these are not the grants you are looking for
61 invalid_client client not found
62 invalid_request client_id was not supplied
63 invalid_request client_secret was not supplied
64 invalid_client Incorrect credentials. Please Retry
65 invalid_request grant_type was not supplied
80 invalid_request invalid channel type
81 invalid_request bad channel handle
83 invalid_request otp not found
84 invalid_request fact verification failed
85 invalid_request otp verification failed
100 invalid_request backend does not know about this username
101 invalid_request code was not supplied
102 invalid_request redirect_uri was not supplied
103 invalid_request code is bad or expired
104 invalid_grant redirect_uri does not match the previous grant
105 invalid_grant this grant was not issued to you!
106 invalid_request refresh_token was not supplied
107 invalid_request refresh disallowed for app
108 invalid_grant bad or expired refresh token
109 invalid_request loginid was not supplied
115 invalid_request unauthenticated client will not be issued token!
117 invalid_request nonce is mandatory for this response_type
118 invalid_request display is invalid
119 invalid_request prompt is invalid
119 invalid_request prompt must be set to consent for offline_access

Migrating old tokens to new Oauth2 Bearer Tokens

Existing applications that use the Pre-2017 Authorization (Deprecated) framework need to move to support the new Oauth2 Bearer Tokens. Applications will need to migrate their existing users who already have connected to it to obtain new Oauth2 tokens without requiring users to reauthorize. This can be done by exchanging an old access token for a new refresh token.

Base URIs

When making API calls, the appropriate base URI for the user's geolocation should be used. See the Base URIs page for the full list.

Exchanging a Token

In order to support new Oauth2, applications need to exchange old access token for new accessToken and refreshToken pair. Once obtained, applications should store these refreshTokens as part of users authorization data.

The new Oauth2 accessToken has a one hour lifetime. Once expired, applications would need to call Oauth2's /v0/token endpoint using a refresh_grant, passing in the user's refreshtoken to obtain a fresh accessToken.

This is significantly different from how the deprecated /net2/Oauth2's method of handling access tokens. Partner's would have to store the new Oauth2 refreshToken instead of the old access token. Before making a call to any of Concur's new v4 APIs, it is advisable to request for a new accessToken before making the API call.

Step 1: Obtain Application Token Clients can exchange OLD tokens for NEW Oauth2 tokens by calling the exchangeRefreshToken/me endpoint. In order to call this endpoint, you would first need to obtain an Application Token by calling the /v0/token endpoint with the client_credentials grant.

The endpoint also supports a parameter called "returnType=companyToken" This parameter allows a partner who already has what is known as a "WSAdmin" token for a client, to exchange that token for a Company level refresh token.

Step 2: Call exchangeRefreshToken

POST /appmgmt/v0/legacyApps/{OLDConsumerKey}/exchangeRefreshToken/me

If you are exchanging a WSAdmin token for a new Company level refresh token:

POST /appmgmt/v0/legacyApps/{OLDConsumerKey}/exchangeRefreshToken/me?returnType=companyToken

Request Header

Name Type Format Description
Authorization string Bearer <accessToken> Required The NEW client_credentials accessToken.

Request Body

Name Type Format Description
token string Required The OLD refreshToken
secret string Required The NEW application client_secret

Sample Curl:

curl -H 'Authorization: Bearer <accessToken>' -d '{"token": "1_oaCof444CaiNXg1FFG$Perr19qIo", "secret": "12345"}' -X POST https://us.api.concursolutions.com/appmgmt/v0/legacyApps/Bwu0mvTHtKYAnBb3Pgu9AW/exchangeRefreshToken/me

successful call, responds with

200 OK
{
  "token": "8c844478-745c-4c45-adf7-1e2777a50dbf",
  "created": 1479407196809,
  "expired": 1494959196809,
  "scopes": [
    "EXPRPT",
    "LIST",
    "BANK",
    "CCARD"
  ],
  "context": "{\"userid\":\"7934467f-dcd1-4631-ba34-3ebd28343e8f\",\"cid\":\"3a55c75e-ac1e-4515-845c-0a4978452828\",\"ptype\":\"user\",\"userURI\":\"https://us.api.concursolutions.com/profile-service/v1/users/7934467f-dcd1-4631-ba34-3ebd28343e8f\",\"scope\":\"EXPRPT LIST BANK CCARD\"}"
}

Sample Curl for WSAdmin token exchange for Company level refreh token:

curl -H 'Authorization: Bearer <accessToken>' -d '{"token": "1_oaCof444CaiNXg1FFG$Perr19qIo", "secret": "12345"}' -X POST https://us.api.concursolutions.com/appmgmt/v0/legacyApps/Bwu0mvTHtKYAnBb3Pgu9AW/exchangeRefreshToken/me?returnType=companyToken

successful call, responds with

200 OK
{
  "token": "8c844478-745c-4c45-adf7-1e2777a50dbf",
  "created": 1479407196809,
  "expired": 1494959196809,
  "scopes": [
    "EXPRPT",
    "LIST",
    "BANK",
    "CCARD"
  ],
  "context": "{\"userid\":\"7934467f-dcd1-4631-ba34-3ebd28343e8f\",\"cid\":\"3a55c75e-ac1e-4515-845c-0a4978452828\",\"ptype\":\"company\",\"userURI\":\"https://us.api.concursolutions.com/profile-service/v1/users/7934467f-dcd1-4631-ba34-3ebd28343e8f\",\"scope\":\"EXPRPT LIST BANK CCARD\"}"
}

Step 3: Obtain New Access Token

Once you have the NEW refreshToken from the response (8c844478-745c-4c45-adf7-1e2777a50dbf) you can then proceed to call /v0/token using the refresh grant to obtain a NEW Oauth2 accessToken.

Sample Curl:

curl -X POST 'https://us.api.concursolutions.com/oauth2/v0/token' -d 'client_id=3a55c75e-ac1e-4515-845c-0a4978452828&client_secret=12345&grant_type=refresh_token&refresh_token=8c844478-745c-4c45-adf7-1e2777a50dbf'

successful call, responds with:

200 OK
{
  "expires_in": 3600,
  "scope": "EXPRPT LIST BANK CCARD",
  "token_type": "Bearer",
  "access_token": "eyJ0...demo...eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6IjE0NTU2MTQzNDYifQ.eyJjb25jdXIuc2NvcGVzIjpbIkVYUFJQVCIsIkxJU1QiLCJCQU5LIiwiQ0NBUkQiXSwiYXVkIjoiKiIsImNvbmN1ci5wcm9maWxlIjoiaHR0cHM6Ly91cy1ycWEzLmFwaS5jb25jdXJzb2x1dGlvbnMuY29tL3Byb2ZpbGUvdjEvcHJpY2lwYWxzLzc5NmI0NjdmLWRjZDEtNDYzMS1iYTg1LTNlYmQyOGIzNmU4ZiIsImNvbmN1ci52ZXJzaW9uIjoyLCJjb25jdXIudHlwZSI6InVzZXIiLCJjb25jdXIuYXBwIjoiaHR0cHM6Ly91cy1ycWEzLmFwaS5jb25jdXJzb2x1dGlvbnMuY29tL3Byb2ZpbGUvdjEvYXBwcy9lMDEwZTI1ZC1iNGNlLTRjZTMtYTdlNiLCJzdWIiOiI3OTZiNDY3Zi1kY2QxLTQ2MzEtYmE4NS0zZWJkMjhiMzZlOGYiLCJpc3MiOiJodHRwczovL3VzLXJxYTMuYXBpLmNvbmN1cnNvbHV0aW9ucy5jb20iLCJleHAiOjE0Nzk0MTU4NjksImxlZ2FjeV9hcHBsaWNhdGlvbl9pZCI6MTUwMDA2MzY1OSwidXNlclVSSSI6Imh0dHBzOi8vdXMtcnFhMy5hcGkuY29uY3Vyc29sdXRpb25zLmNvbS9wcm9maWxlLXNlcnZpY2UvdjEvdXNlcnMvNzk2YjQ2N2YtZGNkMS00NjMxLWJhODUtM2ViZDI4YjM2ZThmIiwidXNlcnV1aWQiOiI3OTZiNDY3Zi1kY2QxLTQ2MzEtYmE4NS0zZWJkMjhiMzZlOGYiLCJuYmYiOjE0Nzk0MTIyNjksImh0dHBzOi8vYXBpLmNvbmN1cnNvbHV0aW9ucyiaHR0cHM6Ly91cy1ycWEzLmFwaS5jb25jdXJzb2x1dGlvbnMuY29tL3Byb2ZpbGUvdjEvYXBwcy9lMDEwZTI1ZC1iNGNlLTRjZTMtYTdlNC1iNjcwY2IxYWRjYjAiLCJodHRwczovL2FwaS5jb25jdXJzb2x1dGlvbnMuY29tL3Njb3BlcyI6WyJFWFBSUFQiLCJMSVNUIiwiQkFOSyIsIkNDQVJEIl0sImlhdCI6MTQ3OTQxMjI2OX0.I4EeqKZbpfFonitGBZnLBb20NwMjZNNp5e1d3-BRsepEcJSVCVYIV9HAB2EkkopvoLJsAittiZgD0iDwuh2WVgUt_c4QGzNc_-rXRtCIeKyPQRvxUZNQ7y5RTqEQFNo7hrtXiNZ-yV30zlbijP-12XU5Cu4n2VXgRKxvcCUr5j0RcovUc6O0aOR7VTzj4ZbiDdijOEtmKWGluAYyfIlz8XF2aErAB5Jff2fr9UvgHgtbleYV7eBSesvd9hJEk4S-OAtmFoJwLDECLtLcBKyeHnPEe7LmkLYShcflWG2_tYk4ysPIMG6ne5kRNxJKsDbkMItjpXhujBEGi7YIPWtFWQ",
  "refresh_token": "31456dcd-b46a-4292-b2d3-f97033338487",
  "geolocation": "https://us.api.concursolutions.com"
}

Migration - Response Codes

HTTP Status returned by exchangeAccessToken

HTTP Status Description
200 OK - Successful call, response is in body.
400 Bad Request - see list of responses below.
404 Not Found
500 Server Error, error message is in body.
503 Server Timed Out, error message is in body.

exchangeAccessToken Response Codes

CODE Description
OK OK - Successful call, response is in body.
INVALIDSCOPES One or more scopes requested are not a subset of the allowed scopes.
INVALIDAPP Application is invalid
INVALIDTOKEN Bad or expired token
UNAUTHORIZED Invalid credentials

HTTP Status returned by oauth2

HTTP Status Description
200 OK - Successful call, response is in body.
400 Bad Request (error, error_description, code)
401 Unauthorized (error, error_description, code)
403 Forbidden (error, error_description, code)
404 Not Found (error, error_description, code)
500 Server Error, error message is in body.
503 Server Timed Out, error message is in body.

4xx class errors have a JSON response with the following fields

{
  "code": <number>,
  "error": <error>,
  "error_description": <error_description>
}

/token

Code Error Description
5 invalid_grant Incorrect credentials. Please Retry
10 invalid_grant Account is disabled. Please contact support
11 invalid_grant Account is disabled. Please contact support
12 invalid_grant Logon Denied. Please contact support
13 invalid_grant Logon Denied. Please contact support
14 invalid_grant Account Locked. Please contact support
16 invalid_request user lives elsewhere
19 invalid_grant Incorrect credentials. Please Retry
51 invalid_request username was not supplied
52 invalid_request password was not supplied
53 invalid_client company is not enabled for this client
54 invalid_scope requested scope exceeds granted scope
55 invalid_request we don't know this email
56 invalid_request otp was not supplied
57 invalid_request channel_type missing
58 invalid_request channel_handle missing
59 access_denied client disabled
60 invalid_grant these are not the grants you are looking for
61 invalid_client client not found
62 invalid_request client_id was not supplied
63 invalid_request client_secret was not supplied
64 invalid_client Incorrect credentials. Please Retry
65 invalid_request grant_type was not supplied
80 invalid_request invalid channel type
81 invalid_request bad channel handle
83 invalid_request otp not found
84 invalid_request fact verification failed
85 invalid_request otp verification failed
100 invalid_request backend does not know about this username
101 invalid_request code was not supplied
102 invalid_request redirect_uri was not supplied
103 invalid_request code is bad or expired
104 invalid_grant redirect_uri does not match the previous grant
105 invalid_grant this grant was not issued to you!
106 invalid_request refresh_token was not supplied
107 invalid_request refresh disallowed for app
108 invalid_grant bad or expired refresh token
109 invalid_request loginid was not supplied
115 invalid_request unauthenticated client will not be issued token!
117 invalid_request nonce is mandatory for this response_type
118 invalid_request display is invalid
119 invalid_request prompt is invalid
119 invalid_request prompt must be set to consent for offline_access

Oauth2 Migration Best Practices

Old World Authentication

New World Authentication

1. Oauth2

2. Oauth2 Migration - Getting Started

3. Token Management

4. Old auth v.s. new auth diagram

old v.s. new

List of Scopes for all SAP Concur APIs

Scope is a parameter as defined in the OAuth 2.0 standards (RFC6749) to enable a client to specify the scope of the access request. The value of the scope parameter is expressed as a list of space-delimited, case-sensitive strings although some implementations of scope uses a comma-delimited format. Scopes limit access for OAuth2 tokens and do not grant any additional permission beyond that which the client already has.

Scopes apply to applications only. Scopes play a crucial part in defining the ultimate access to a resource by a User.

User’s Roles / Permissions + Claims + Application Scopes

Naming Conventions

Concur services follow these standard naming conventions for scopes.

Template: {resource}.{optional subresource}.{action}
Examples: mileage.rate.read
          receipts.read

List of v4 Actions

{actions} are common authorizations across resources.

Action Description Examples
read Read only access (GET) receipts.read, budgetitem.read
write Read AND Write access (GET, POST, UPDATE etc) company.write, travel.receipts.write
writeonly Write only access mileage.journey.writeonly, receipts.writeonly
delete Delete access N/A

List of v4 API Scopes

These are the list of scopes for the v4+ APIs.

Scope Description
budgetitem.read Read access to budget data including fiscal calendar.
budgetitem.write Read and write access to budget data including fiscal calendar.
company.read Read company profile
company.write Read and Write company profile
creditcardaccount.read Read credit card account data
quickexpense.writeonly Write quick expense
fiscalcalendar.read Access to fiscal calendar
fiscalcalendar.write Read and write access to fiscal calendar.
mileage.journey.read Read-only access to mileage journey resources.
mileage.journey.writeonly Write-only access to mileage journey resources.
mileage.vehicle.read Read-only access to vehicle resources.
mileage.vehicle.writeonly Write-only access to vehicle resources.
mileage.rate.read Read-only access to rate configuration resources.
mileage.rate.writeonly Write-only access to rate configuration resources.
notifications.messages.writeonly Write messages to the notifications platform
openid Return OPENID Token
realtimeingest.location.writeonly Post user location object upon trip completion
receipts.read Read receipts and invoices
receipts.write Read and Write receipts and invoices
receipts.writeonly Write only access for receipts and invoices
travel.receipts.read Read requests for travel receipts
travel.receipts.write Read and Write travel receipts
travelallowance.itinerary.read Read only access to Itinerary data
travelallowance.itinerary.writeonly Write only access to Itinerary Data
travelallowance.configuration.read Read only access to Itinerary Configuration data
travelallowance.configuration.writeonly Write only access to Itinerary Configuration data
travelallowance.itineraryresult.read Read only access to Itinerary Result data
travelrequest.write Read and write Travel Requests
user.read Read user profile
user.write Read and Write user profile
purchaserequest.write Write only access to Purchase Requests
purchaserequest.read Read only access Purchase Requests

List of Connect API scopes

These are the list of scopes for the existing CONNECT APIs (v1.0 - v3.1)

Scope Description
user_read Read user profile for old USER APIs
ATTEND Attendee List - Add, Update, or Inactivate Attendees
CONFIG Expense Configuration - Update Expense Feature Configuration
CONREQ Connection Request - Get or update connection requests to travel reward programs
ERECPT E-Receipts Provider - Post receipts and invoices, get matching facts
EVS External Validation - Validate Fields Using External Systems
EXPRPT Expense Report - Add, Approve, or Update Expense Reports
CCARD Expense Report - Add, Approve, or Update Expense Reports
BANK Expense Report - Add, Approve, or Update Expense Reports
EXTRCT Extract - Request Extract of Available Data
FISVC Financial Integration - Migrate transactions from Concur to external systems
FOP Form of Payment - Access and update user form of payment information
GHOST Form of Payment - Access and update user form of payment information
IMAGE Imaging - Add or Retrieve Report and Line Item Images
INSGHT Insights - Additional services marketable to users
INVPMT Payment Request - Create ,Retrieve and Update for Payment Request
INVPO Purchase Orders - Add or Update Purchase Orders
INVTV Invoice - Tax Validation
INVVEN Search, Add, Update or Delete Vendors
ITINER Itinerary - Add or Update Itineraries or Bookings
JOBLOG Job Log - Log Start, Detail, End and Ping
LIST List Items - Add, Update, or Delete List Items
MTNG Meeting - Attendee Travel Booking
NOTIF Notifications - View and manage notifications
PAYBAT Payment Batch - Close Batches and Request Batch Export Files
RCTIMG Receipts - Add or Update Receipt and OCR Images
SUPSVC Supplier Service - Get Supplier Data
TAXINV Digital Tax Invoice - Get or Validate Digital Tax Invoices
TRVPRF Travel Profile - Access and update user travel profile information
PASSV Travel Profile - Access and update user travel profile information
COMPD Travel Profile - Access and update user travel profile information
EMERG Travel Profile - Access and update user travel profile information
TSAI Travel Profile - Access and update user travel profile information
TMCSP Travel Profile - Access and update user travel profile information
MEDIC Travel Profile - Access and update user travel profile information
UNUTX Travel Profile - Access and update user travel profile information
TRVPTS Travel Points - Access User Balances and Post Travel Points Transactions
TRVREQ Travel Request - Add, Update or Delete Travel Requests
TWS Travel Approval - Approve or Reject Travel Itineraries
USER Users- Add or Update User Accounts
COMPANY Companies - Add or Update Company profile

Budget v4

Budget v4 - Getting Started

Getting Started

Overview

The Budget service exposes budget and fiscal year data. Partners and clients may use the service endpoints to read and alter fiscal year, budget, budget adjustment, and budget matching configuration. Summary and detailed balance amounts are also available to read, but may not be altered via the API.

The sequence to configure budgets is to first setup the fiscal year and then the budget categories (if applicable) before creating budget items. Budget items may use budget tracking fields as filters. The budget tracking field can only be configured in the application UI. Also budget owner, approver, and budget viewer permissions have to be assigned to users prior to configuring budgets.

Process Flow

A process flow diagram of getting started with Budget APIs

Products and Editions

Scope Usage

This API requires one or more of the following scopes:

Name Description Endpoint
budgetitem.read Grants read access to the budget resources. GET Budget Category, GET Budget Item, GET Budget Tracking Fields, GET Fiscal Year, GET Valid Expense Types
budgetitem.write Grants read and write access to the budget resources. GET Budget Category, GET Budget Item, GET Budget Tracking Fields, GET Fiscal Year, GET Valid Expense Types, POST Budget Adjustment, POST Budget Category, POST Budget Item, POST Fiscal Year, DELETE Budget Category, DELETE Budget Item, DELETE Fiscal Year
fiscalcalendar.read Grants read access to the fiscal calendar. GET All Fiscal Years, GET a Fiscal Year
fiscalcalendar.write Grants read and write access to the fiscal calendar. GET All Fiscal Years, GET a Fiscal Year, POST a Fiscal Year, DELETE a Fiscal Year

Dependencies

SAP Concur clients must purchase Budget in order to use this API.

Access Token Usage

This API supports both company level and user level access tokens. The user needs to have the Budget Administrator role in order to access the API.

Budget v4 - Fiscal Year 2020

The Fiscal Calendar is used both for Reporting and Budget. A fiscal year can start and end at any date as long as the end date is after the start date and does not span more than two years. Fiscal years cannot overlap. Fiscal periods cannot overlap and are limited to 24 per fiscal year.

GET All Fiscal Years

Retrieve a list of all fiscal years

Scopes

This API call requires one of the following scopes:

Request

URI

GET  /budget/v4/fiscalYear

Template

Parameters

Name Type Format Description
lastModifiedAfter datetime YYYY-MM-DDTHH:MM:SS Use this field if you only want Fiscal Years that were changed after the supplied date. The supplied date will be interpreted in the UTC time zone. If lastModifiedAfter is not supplied, the service will return all Fiscal Years, regardless of modified date. Example: 2016-03-29T16:12:20
includeRemoved boolean query If true, the service will return all Fiscal Years, including those that were previously removed. If not supplied, this field defaults to false.

Headers

Response

Status Codes

Headers

Response Headers

Payload

Fiscal Year

Example

GET https://us.api.concursolutions.com/budget/v4/fiscalYear?lastModifiedAfter=2017-02-27T12:30:00
Authorization: Bearer {token}
Content-Type: application/json

Request

HTTP/1.1 200 OK
Cache-Control: max-age=604800
Content-Type: application/json
Date: Wed, 06 Jul 2020 17:33:03 GMT
Etag: "359670651"
Expires: Wed, 13 Jul 2020 17:33:03 GMT
Last-Modified: Fri, 09 Aug 2020 23:54:35 GMT
Content-Length: 2187
concur-correlationid: ffa4ae0a-f65c-4037-8bfb-8996c3fca28c

Response

[
    {
      "name":"2017",
      "startDate":"2017-01-01",
      "endDate":"2017-12-31",
      "status":"OPEN",
      "id":"5e58b9b1-fed6-4d36-a5a1-a1ed325931d4",
      "lastModified":"2017-03-26 20:53:19",
      "currentYear":false,
      "monthlyFiscalPeriods":[
        {
          "name":"2017 - Aug",
          "fiscalPeriodStatus":"OPEN",
          "id":"a4e94128-c7b7-4561-a57e-1512e59e4896",
          "periodType":"MONTHLY",
          "startDate":"2017-08-01",
          "endDate":"2017-08-31",
          "spendDate":null,
          "fiscalYearId":"5e58b9b1-fed6-4d36-a5a1-a1ed325931d4",
          "currentPeriod":false
        },
        {
          "name":"2017 - Jan",
          "fiscalPeriodStatus":"CLOSED",
          "id":"ab2810f5-f045-45b0-b2b2-8e84bc978e27",
          "periodType":"MONTHLY",
          "startDate":"2017-01-01",
          "endDate":"2017-01-30",
          "spendDate":null,
          "fiscalYearId":"5e58b9b1-fed6-4d36-a5a1-a1ed325931d4",
          "currentPeriod":false
        },
        {
          "Additional fiscal periods removed for brevity": "Additional fiscal periods removed for brevity"
        }
      ],
      "quarterlyFiscalPeriods":[
        {"name":"2017 - Q4",
          "fiscalPeriodStatus":"OPEN",
          "id":"655ffe9d-caca-4f2f-a4a1-e04cfb68fd6e",
          "periodType":"QUARTERLY",
          "startDate":"2017-10-01",
          "endDate":"2017-12-31",
          "spendDate":null,
          "fiscalYearId":"5e58b9b1-fed6-4d36-a5a1-a1ed325931d4",
          "currentPeriod":false
        },
        {
          "Additional fiscal periods removed for brevity": "Additional fiscal periods removed for brevity"
        }
      ],
      "yearlyFiscalPeriods":[
        {
          "name":"2017",
          "fiscalPeriodStatus":"OPEN",
          "id":"2fb8ea93-172a-47a6-9611-44eb75ad547b",
          "periodType":"YEARLY",
          "startDate":"2017-01-01",
          "endDate":"2017-12-31",
          "spendDate":null,
          "fiscalYearId":"5e58b9b1-fed6-4d36-a5a1-a1ed325931d4",
          "currentPeriod":false
        }
      ],
      "customFiscalPeriods":[]
    }
]

GET a Fiscal Year

Retrieve a single fiscal year by ID.

Scopes

This API call requires one of the following scopes:

Request

URI

Template

GET  /budget/v4/fiscalYear/{id}

Parameters

Name Type Format Description
id string uuid The fiscal year's key field.

Headers

Response

Status Codes

Headers

Response Headers

Payload

Fiscal Year

Example

GET https://us.api.concursolutions.com/budget/v4/fiscalYear/5e58b9b1-fed6-4d36-a5a1-a1ed325931d4
Authorization: Bearer {token}

Request

HTTP/1.1 200 OK
Cache-Control: max-age=604800
Content-Type: application/json
Date: Wed, 06 Jul 2020 17:33:03 GMT
Etag: "359670651"
Expires: Wed, 13 Jul 2020 17:33:03 GMT
Last-Modified: Fri, 09 Aug 2020 23:54:35 GMT
Content-Length: 1270
concur-correlationid: 39216840-2808-4c49-8874-e9862d96fdb6

Response

{
  "name":"2017",
  "startDate":"2017-01-01",
  "endDate":"2017-12-31",
  "status":"OPEN",
  "id":"5e58b9b1-fed6-4d36-a5a1-a1ed325931d4",
  "lastModified":"2017-03-26 20:53:19",
  "currentYear":false,
  "monthlyFiscalPeriods":[
    {
      "name":"2017 - Aug",
      "fiscalPeriodStatus":"OPEN",
      "id":"a4e94128-c7b7-4561-a57e-1512e59e4896",
      "periodType":"MONTHLY",
      "startDate":"2017-08-01",
      "endDate":"2017-08-31",
      "spendDate":null,
      "fiscalYearId":"5e58b9b1-fed6-4d36-a5a1-a1ed325931d4",
      "currentPeriod":false
    },
    {
      "name":"2017 - Jan",
      "fiscalPeriodStatus":"CLOSED",
      "id":"ab2810f5-f045-45b0-b2b2-8e84bc978e27",
      "periodType":"MONTHLY",
      "startDate":"2017-01-01",
      "endDate":"2017-01-30",
      "spendDate":null,
      "fiscalYearId":"5e58b9b1-fed6-4d36-a5a1-a1ed325931d4",
      "currentPeriod":false
    },
    {
      "Additional fiscal periods removed for brevity": "Additional fiscal periods removed for brevity"
    }
  ],
  "quarterlyFiscalPeriods":[
    {"name":"2017 - Q4",
      "fiscalPeriodStatus":"OPEN",
      "id":"655ffe9d-caca-4f2f-a4a1-e04cfb68fd6e",
      "periodType":"QUARTERLY",
      "startDate":"2017-10-01",
      "endDate":"2017-12-31",
      "spendDate":null,
      "fiscalYearId":"5e58b9b1-fed6-4d36-a5a1-a1ed325931d4",
      "currentPeriod":false
    },
    {
      "Additional fiscal periods removed for brevity": "Additional fiscal periods removed for brevity"
    }
  ],
  "yearlyFiscalPeriods":[
    {
      "name":"2017",
      "fiscalPeriodStatus":"OPEN",
      "id":"2fb8ea93-172a-47a6-9611-44eb75ad547b",
      "periodType":"YEARLY",
      "startDate":"2017-01-01",
      "endDate":"2017-12-31",
      "spendDate":null,
      "fiscalYearId":"5e58b9b1-fed6-4d36-a5a1-a1ed325931d4",
      "currentPeriod":false
    }
  ],
  "customFiscalPeriods":[],
  "displayName":"2017-Special"
}

POST Fiscal Year(s)

Create or update a list of one or more fiscal years.

Scopes

This API call requires one of the following scopes:

Request

URI

Template

POST  /budget/v4/budgetCategory

Parameters

N/A

Headers

Payload

Fiscal Year

Response

Status Codes

Headers

Response Headers

Payload

Fiscal Year or Error Response

Example

POST https://us.api.concursolutions.com/budget/v4/fiscalYear
Authorization: Bearer {token}

Request

[
  {
    "name":"2017-Special",
    "startDate":"2017-01-01",
    "endDate":"2017-03-31",
    "status":"OPEN",
    "monthlyFiscalPeriods":[
      {
        "name":"2017-Special - Jan",
        "fiscalPeriodStatus":"OPEN",
        "periodType":"MONTHLY",
        "startDate":"2017-01-01",
        "endDate":"2017-01-31"
      },
      {
        "name":"2017-Special - Feb",
        "fiscalPeriodStatus":"OPEN",
        "periodType":"MONTHLY",
        "startDate":"2017-02-01",
        "endDate":"2017-02-28"
      },
      {
        "name":"2017-Special - Mar",
        "fiscalPeriodStatus":"OPEN",
        "periodType":"MONTHLY",
        "startDate":"2017-03-01",
        "endDate":"2017-03-31"
      }
    ],
    "displayName":"2017-Special"
  }
]

Response

Success Response

HTTP/1.1 200 OK
Cache-Control: max-age=604800
Content-Type: application/json
Date: Wed, 06 Jul 2020 17:33:03 GMT
Etag: "359670651"
Expires: Wed, 13 Jul 2020 17:33:03 GMT
Last-Modified: Fri, 09 Aug 2020 23:54:35 GMT
Content-Length: 1270
concur-correlationid: 5c00e59f-d00c-4019-8d3d-47130d8e37b4
[
    {
      "name":"2017-Special",
      "startDate":"2017-01-01",
      "endDate":"2017-03-31",
      "status":"OPEN",
      "id":"2edd7bd4-8f10-46e5-bf52-d553f6c7df80",
      "lastModified":"2018-03-26 20:54:11",
      "currentYear":false,
      "monthlyFiscalPeriods":[
        {
          "name":"2017-Special - Jan",
          "fiscalPeriodStatus":"OPEN",
          "periodType":"MONTHLY",
          "startDate":"2017-01-01",
          "endDate":"2017-01-31",
          "id":"1929d1d9-6c99-4635-9272-508364193f8f",
          "spendDate":null,
          "fiscalYearId":"2edd7bd4-8f10-46e5-bf52-d553f6c7df80",
          "currentPeriod":false
        },
        {
          "name":"2017-Special - Feb",
          "fiscalPeriodStatus":"OPEN",
          "periodType":"MONTHLY",
          "startDate":"2017-02-01",
          "endDate":"2017-02-28",
          "id":"41aa7452-e52a-4fd6-9c8a-5b199edeadaf",
          "spendDate":null,
          "fiscalYearId":"2edd7bd4-8f10-46e5-bf52-d553f6c7df80",
          "currentPeriod":false
        },
        {
          "name":"2017-Special - Mar",
          "fiscalPeriodStatus":"OPEN",
          "periodType":"MONTHLY",
          "startDate":"2017-03-01",
          "endDate":"2017-03-31",
          "id":"6c7d0b13-96b9-4d76-a083-4d38c96144e2",
          "spendDate":null,
          "fiscalYearId":"2edd7bd4-8f10-46e5-bf52-d553f6c7df80",
          "currentPeriod":false
        }
      ],
      "quarterlyFiscalPeriods":[
        {
          "name":"2017-Special - Q1",
          "fiscalPeriodStatus":"OPEN",
          "id":"5ce25dfd-8b2b-4fea-91eb-f8f9ad0bb896 ",
          "periodType":"QUARTERLY",
          "startDate":"2017-01-01",
          "endDate":"2017-03-31",
          "spendDate":null,
          "fiscalYearId":"2edd7bd4-8f10-46e5-bf52-d553f6c7df80",
          "currentPeriod":false
        }
      ],
      "yearlyFiscalPeriods":[
        {
          "name":"2017-Special",
          "fiscalPeriodStatus":"OPEN",
          "id":"a6bede66-4f3d-412f-a620-2a073013cb2a",
          "periodType":"YEARLY",
          "startDate":"2017-01-01",
          "endDate":"2017-03-31",
          "spendDate":null,
          "fiscalYearId":"2edd7bd4-8f10-46e5-bf52-d553f6c7df80",
          "currentPeriod":false
        }
      ],
      "customFiscalPeriods":[],
      "displayName":"2017-Special"
    }
]

Failure Response

HTTP/1.1 400 Bad Request
Cache-Control: no-store
Connection: close
Content-Length: 338
Content-Type: application/json;charset=utf-8
Date: Fri, 21 Sep 2018 15:27:05 GMT
Expires: Thu, 20 Sep 2018 15:27:05 GMT
Pragma: no-cache
concur-correlationid: cb061832-82eb-418e-a968-de6b4ce370ae
{
  "status" : false,
  "errorMessageList" : [
    {
      "errorType" : "ERROR",
      "errorCode" : "BUDGET.FISCAL_YEAR_SDATE_ERROR",
      "errorMessage" : "Fiscal year should have a start date"
    },
    {
      "errorType" : "ERROR",
      "errorCode" : "BUDGET.FISCAL_YEARS_HAVE_GAP",
      "errorMessage" : "Fiscal years should not have gaps between them"
    }
  ]
}

DELETE a Fiscal Year

Delete a fiscal year. Fiscal years that are in use may not be deleted.

Scopes

This API call requires one of the following scopes:

Request

URI

Template
DELETE  /budget/v4/fiscalYear/{id}

Parameters

Name Type Format Description
id string uuid The fiscal years's key field.

Headers

Response

Status Codes

Headers

Response Headers

Example

Request

DELETE https://us.api.concursolutions.com/budget/v4/fiscalYear/a11cfc7c-967f-415f-9b30-23f8ce2dbf69
Authorization: Bearer {token}

Response

HTTP/1.1 200 OK
Cache-Control: max-age=604800
Content-Type: application/json
Date: Wed, 06 Jul 2020 17:33:03 GMT
Etag: "359670651"
Expires: Wed, 13 Jul 2020 17:33:03 GMT
Last-Modified: Fri, 09 Aug 2020 23:54:35 GMT
Content-Length: 1270
concur-correlationid: eb7cf20a-3481-45a5-808c-98b8ef7fe805

Fiscal Year - Schema

Get a FiscalYear

Name Type Format Description
currentYear boolean - READ ONLY True if this the current fiscal year based on the current date and time, False otherwise.
startDate date YYYY-MM-DD Required The start date for this fiscal year. The distance between start date and end date may not be more than two years.
endDate date YYYY-MM-DD Required The end date for this fiscal year. The distance between start date and end date may not be more than two years.
name datetime - Required The name of this fiscal year. Must be unique for this entity.
status string - Required The status of this fiscal year. Supported values: OPEN, CLOSED, REMOVED
id string - The budget service's key for this object.
lastModified datetime - READ ONLY The UTC date and time when this object was last changed.
monthlyFiscalPeriods array fiscalPeriod Required The list of monthly fiscal periods in this fiscal year. Fiscal periods must complete fill the parent fiscal year with no overlaps.
quarterlyFiscalPeriods array fiscalPeriod READ ONLY The list of quarterly fiscal periods in this fiscal year. If this parameter is not specified, quarterly fiscal periods are automatically generated based on the monthly fiscal periods supplied.
yearlyFiscalPeriods array fiscalPeriod READ ONLY The list of yearly fiscal periods in this fiscal year. If this parameter is not specified, one period is created that fills the fiscal year.
customFiscalPeriods array fiscalPeriod READ ONLY The list of custom fiscal periods in this fiscal year. Custom fiscal periods are API-only and will not display on user budget dashboards.
openAndClosedFiscalPeriods array fiscalPeriod READ ONLY The list of all fiscal periods in this fiscal year, sorted by status.
fiscalPeriods array fiscalPeriod READ ONLY The list of all fiscal periods in this fiscal year.
displayName string - READ ONLY Display name for fiscal year. For date range budget item we use this field to display.

Get a - FiscalPeriod

Name Type Format Description
currentPeriod boolean - READ ONLY True if this the current fiscal period based on the current date and time, False otherwise.
startDate date YYYY-MM-DD Required The start date for this fiscal period. Must be within the parent fiscal year.
endDate date YYYY-MM-DD Required The end date for this fiscal year. Must be within the parent fiscal year.
name string - Required The name of this fiscal period. Must be unique for this entity.
fiscalPeriodStatus string - Required The status of this fiscal period. Supported values: OPEN, CLOSED, REMOVED
periodType string - Required The type of fiscal period. Supported values: MONTHLY, QUARTERLY, YEARLY, CUSTOM
fiscalYearId string - The key of the parent fiscal year for this fiscal period.
id string - The budget service's key for this object.
spendDate date - READ ONLY If the current date is after this fiscal period's start date, this field shows the current date.

Budget v4 - Error Response

Name Type Format Description
status boolean - False if there was an error.
errorMessageList array errorMessage List of all errors detected.

Budget v4 - Error Message

Name Type Format Description
errorType String - WARNING or ERROR.
errorCode String - Text code for this error.
errorMessage String - Plain language error message.

Response Headers

Budget v4 - Budget Category

This resource is used to retrieve and update budget categories which are collections of expense types used for budget matching. Each budget item header may have one Budget Category. If it does, only line items with expense types contained in that Budget Category will be accumulated to the budget.

GET All Budget Categories

Retrieve a list of all budget categories.

Scopes

This API call requires one of the following scopes:

Request

URI

GET /budget/v4/budgetCategory

Template

Parameters

N/A

Headers

Response

Status Codes

Headers

Response Headers

Payload

Budget Category

Example

GET https://us.api.concursolutions.com/budget/v4/budgetCategory
Authorization: Bearer {token}
Content-Type: application/json

Request

HTTP/1.1 200 OK
Cache-Control: max-age=604800
Content-Type: application/json
Date: Wed, 06 Jul 2020 17:33:03 GMT
Etag: "359670651"
Expires: Wed, 13 Jul 2020 17:33:03 GMT
Last-Modified: Fri, 09 Aug 2020 23:54:35 GMT
Content-Length: 1292
concur-correlationid: 9d59b6f0-e5bd-47bf-bcad-4c3de9f5c45c

Response

[
    {
      "name":"Marketing and Outreach",
      "description":null,
      "statusType":"OPEN",
      "id":"36047f6c-6cf6-443d-a952-39efb012acdb",
      "expenseTypes":[
        {
          "featureTypeCode":"PURCHASE_REQUEST",
          "expenseTypeCode":"MKTG",
          "id":"f35827a8-7981-4a5b-bfc3-da7ebb4665ff",
          "name":null
        },
        {
          "featureTypeCode":"EXPENSE",
          "expenseTypeCode":"SEMNR",
          "id":"30f16783-e50e-4ab4-b6fb-f66cc75956f2",
          "name":null
        },
        {
          "featureTypeCode":"PURCHASE_REQUEST",
          "expenseTypeCode":"ADVT",
          "id":"64a04928-37b0-49c8-99e8-c346e6d47825",
          "name":null
        }
      ]
    },
    {
      "name":"Airfare",
      "description":null,
      "statusType":"OPEN",
      "id":"459fe79a-9b1e-4ea0-8416-19de0ff14eef",
      "expenseTypes":[
        {
          "featureTypeCode":"EXPENSE",
          "expenseTypeCode":"AIRFR",
          "id":"53300041-3fb9-4a93-8cdf-327fcbe74a0c",
          "name":null
        },
        {
          "featureTypeCode":"REQUEST",
          "expenseTypeCode":"AIRFR",
          "id":"29278c5a-624a-4dd6-a2c1-02dd233d3fbf",
          "name":null
        }
      ]
    }     
]

GET a Budget Category

Retreive the details of a single budget category.

Scopes

This API call requires one of the following scopes:

Request

URI

Template

GET  /budget/v4/budgetCategory/{id}

Parameters

Name Type Format Description
id string uuid The budget category's key field.

Headers

Response

Status Codes

Headers

Response Headers

Payload

Budget Category

Example

GET https://us.api.concursolutions.com/budget/v4/budgetCategory/36047f6c-6cf6-443d-a952-39efb012acdb
Authorization: Bearer {token}
Content-Type: application/json

Request

HTTP/1.1 200 OK
Cache-Control: max-age=604800
Content-Type: application/json
Date: Wed, 06 Jul 2020 17:33:03 GMT
Etag: "359670651"
Expires: Wed, 13 Jul 2020 17:33:03 GMT
Last-Modified: Fri, 09 Aug 2020 23:54:35 GMT
Content-Length: 642
concur-correlationid: f7b1a193-46cc-4784-9c6f-d8e1e47ecaa1

Response

{
  "name":"Marketing and Outreach",
  "description":null,
  "statusType":"OPEN",
  "id":"36047f6c-6cf6-443d-a952-39efb012acdb",
  "expenseTypes":[
    {
      "featureTypeCode":"PURCHASE_REQUEST",
      "expenseTypeCode":"MKTG",
      "id":"f35827a8-7981-4a5b-bfc3-da7ebb4665ff",
      "name":null
    },
    {
      "featureTypeCode":"EXPENSE",
      "expenseTypeCode":"SEMNR",
      "id":"30f16783-e50e-4ab4-b6fb-f66cc75956f2",
      "name":null
    },
    {
      "featureTypeCode":"PURCHASE_REQUEST",
      "expenseTypeCode":"ADVT",
      "id":"64a04928-37b0-49c8-99e8-c346e6d47825",
      "name":null
    }
  ]
}

POST a Budget Category

Save a new budget category or update an existing budget category.

Scopes

budgetitem.write - Refer to Scope Usage for full details.

Request

URI

Template

POST  /budget/v4/budgetCategory

Parameters

N/A

Headers

Payload

Budget Category

Response

Status Codes

Headers

Response Headers

Payload

Budget Category or Error Response

Example

POST https://us.api.concursolutions.com/budget/v4/budgetCategory
Authorization: Bearer {token}
Content-Type: application/json

Request

{
  "name": "Advertising Category",
  "description": "Advertising",
  "expenseTypes": [
    {
      "featureTypeCode": "EXPENSE",
      "expenseTypeCode": "ADVT"
    },
    {
      "featureTypeCode": "PAYMENT_REQUEST",
      "expenseTypeCode": "ADVT"
    }
  ],
  "statusType": "OPEN"
}

Response

Success Response

HTTP/1.1 200 OK
Cache-Control: max-age=604800
Content-Type: application/json
Date: Wed, 06 Jul 2020 17:33:03 GMT
Etag: "359670651"
Expires: Wed, 13 Jul 2020 17:33:03 GMT
Last-Modified: Fri, 09 Aug 2020 23:54:35 GMT
Content-Length: 1270
concur-correlationid: 5c00e59f-d00c-4019-8d3d-47130d8e37b4
{
  "name": "Advertising Category",
  "description": "Advertising",
  "id": "d9fd5191-7016-4f50-a6c8-4770bddc01d8",
  "statusType": "OPEN",
  "expenseTypes": [
    {
      "id": "e1dd44da-25b4-4180-8d89-00f3a8d8cf4e",
      "featureTypeCode": "EXPENSE",
      "expenseTypeCode": "ADVT",
      "name": null
    },
    {
      "id": "67253ac1-77e0-4d61-a478-0d194611b320",
      "featureTypeCode": "PAYMENT_REQUEST",
      "expenseTypeCode": "ADVT",
      "name": null
    }
  ]
}

Failure Response

HTTP/1.1 400 Bad Request
Cache-Control: no-store
Connection: close
Content-Length: 338
Content-Type: application/json;charset=utf-8
Date: Fri, 21 Sep 2018 15:27:05 GMT
Expires: Thu, 20 Sep 2018 15:27:05 GMT
Pragma: no-cache
concur-correlationid: 44adb686-a624-4ee5-b618-e4ea31a95bec
{
  "status" : false,
  "errorMessageList" : [
    {
      "errorType" : "ERROR",
      "errorCode" : "BUDGET.BUDGET_CATEGORY_NAME_REQUIRED",
      "errorMessage" : "Budget category name is required"
    },
    {
      "errorType" : "ERROR",
      "errorCode" : "BUDGET.BUDGET_CATEGORY_NAME_UNIQUE_ERROR",
      "errorMessage" : "Budget category must have a unique name"
    }
  ]
}

DELETE a Budget Category

Delete a budget category. Budget categories that are in use by budget items may not be deleted.

Scopes

budgetitem.write - Refer to Scope Usage for full details.

Request

URI

DELETE  /budget/v4/budgetCategory/{id}

Template

Parameters

Name Type Format Description
id string uuid The budget category's key field.

Headers

Response

Status Codes

Headers

Response Headers

Example

Request

DELETE https://us.api.concursolutions.com/budget/v4/budgetCategory/a5e00b3f-b941-4522-8b0e-07412fb2cc7c
Authorization: Bearer {token}
Content-Type: application/json

Response

HTTP/1.1 200 OK
Cache-Control: max-age=604800
Content-Type: application/json
Date: Wed, 06 Jul 2020 17:33:03 GMT
Etag: "359670651"
Expires: Wed, 13 Jul 2020 17:33:03 GMT
Last-Modified: Fri, 09 Aug 2020 23:54:35 GMT
Content-Length: 0
concur-correlationid: 39216840-2808-4c49-8874-e9862d96fdb6

GET All Valid Expense Types

Retrieve a list of all possible expense types that may be used in a budget category.

Scopes

This API call requires one of the following scopes:

Request

URI

Template

GET  /budget/v4/budgetCategory/expenseTypes

Parameters

N/A

Headers

Response

Status Codes

Headers

Response Headers

Payload

Expense Type

Example

Request

GET https://us.api.concursolutions.com/budget/v4/budgetCategory/expenseTypes
Authorization: Bearer {token}
Accept: application/json

Response

HTTP/1.1 200 OK
Cache-Control: max-age=604800
Content-Type: application/json
Date: Wed, 06 Jul 2020 17:33:03 GMT
Etag: "359670651"
Expires: Wed, 13 Jul 2020 17:33:03 GMT
Last-Modified: Fri, 09 Aug 2020 23:54:35 GMT
Content-Length: 367
concur-correlationid: 7afa7091-bc4e-4408-8248-a67f9e24a023
[
  {
    "featureTypeCode":"EXPENSE",
    "expenseTypeCode":"AIRFR",
    "id":null,
    "name":"Airfare"
  },
  {
    "featureTypeCode":"EXPENSE",
    "expenseTypeCode":"AIRTX",
    "id":null,
    "name":"Airfare Ticket Tax"
  },
  {
    "featureTypeCode":"PAYMENT_REQUEST",
    "expenseTypeCode":"CATER",
    "id":null,
    "name":"Catering"
  }
]

Budget Category - Schema

BudgetCategory

Name Type Format Description
description string - The friendly name for this category.
expenseTypes array expenseType Required The list of expense types that this budget category matches.
name string - Required The admin-facing name for this category.
statusType string - The status of this budget category. Supported values: OPEN, REMOVED
id string - The unique identifier for the budget category.

ExpenseType

Name Type Format Description
featureTypeCode string - Required The type of feature that this expense type applies to: Purchase Request, Payment Request (Invoice), Expense, or Travel Authorization. Supported values: PURCHASE_REQUEST, PAYMENT_REQUEST, EXPENSE, REQUEST
expenseTypeCode string - Required The alphanumeric code that describes an expense type (Example: MEALS, AC_CATER). Any string may be used, but only expense type codes returned by GET /budgetCategory/expenseType will behave properly in the SAP Concur UI.
name string - READ ONLY The name for this expense type if it maps to an expense type set up in SAP Concur.
id string - The budget service's key for this object. If this field is not supplied, the service will use an existing expense type entry if one exists.

Budget Category - Error Response

Name Type Format Description
status boolean - False if there was an error.
errorMessageList array errorMessage List of all errors detected.

Budget Category - Error Message

Name Type Format Description
errorType String - WARNING or ERROR.
errorCode String - Text code for this error.
errorMessage String - Plain language error message.

Budget Category - Response Headers

Budget v4 - Budget Item

Budget Item

This resource is used to retrieve and update information about a budget that spans a single fiscal year. Each budget has multiple details that correspond to fiscal periods - months, quarters, or a single period for a yearly budget.

GET All Budget Items

Retrieve all budget items in groups of up to 50 items. Due to response size and performance considerations, this endpoint does not return budgetItemDetails. Use the GET a Budget Item to retrieve all the details for a single budget.

Scopes

This API call requires one of the following scopes:

Request

URI

GET /budget/v4/budgetItemHeader

Template

Parameters

Name Type Format Description
adminView boolean query If true, returns all budgets for this entity, if false, returns only the budgets owned by the current user. Default: false
offset integer query The start of the page offset. Default: 0

Headers

Response

Status Codes

Headers

Response Headers

Payload

Budget Item Header List

Example

GET https://us.api.concursolutions.com/budget/v4/budgetItemHeader
Authorization: Bearer {token}
Accept: application/json

Request

HTTP/1.1 200 OK
Cache-Control: max-age=604800
Content-Type: application/json
Date: Wed, 06 Jul 2020 17:33:03 GMT
Etag: "359670651"
Expires: Wed, 13 Jul 2020 17:33:03 GMT
Last-Modified: Fri, 09 Aug 2020 23:54:35 GMT
Content-Length: 1270
concur-correlationid: dd6cee88-b725-4c06-9ee9-0ca4ae4f16b2

Response

{
  "totalRows":122,"offset":0,"limit":50,
  "budgetItemHeaders":[
    {
        "name":"Marketing-US-Jean Normandy",
        "isTest":false,
        "budgetItemStatusType":"OPEN",
        "description":"Marketing-US",
        "id":"72eee673-3d81-49c2-966a-b63c7a9302e6",
        "costObjects":[
         {
          "code": "6",
          "fieldDefinitionId": "86eee673-3d81-49c2-966a-b63c7a9302e2",
          "value": "2",
          "listKey": "1334",
          "operator": "EQUAL",
          "displayName": "Country Code"
        }
        ],
        "periodType":"YEARLY",
        "active":true,
        "owned":false,
        "budgetAmounts":{
          "pendingAmount":1178.37697091,
          "unExpensedAmount":2310.73578092,
          "spendAmount":35.78378912,
          "adjustedBudgetAmount": 0,
          "availableAmount":8785.83923997,
          "unExpensedSettings":null,
          "threshold":"UNDER",
          "consumedPercent":12
        },
        "createdDate": "2019-06-26T17:49:53.102Z",
        "budgetItemHeaderId":"72eee673-3d81-49c2-966a-b63c7a9302e6",
        "budgetName":"Marketing-US-Jean Normandy",
        "currencyCode":"EUR",
        "annualBudget":10000.00000000,
        "budgetCategory":{
          "name":"airfare",
          "description":null,
          "statusType":"OPEN",
          "id":"27451c2d-9121-44bd-b4b0-f2119d2071c7"
        },
        "owner":{
          "externalUserCUUID":"8002250890004822936",
          "employeeUuid":"210fe25f-e326-495c-847a-de333173f616",
          "id":"f779261d-77ce-4123-b739-d842ef6f104d",
          "name":"Jean Normandy",
          "email":"jean.normandy@xyz.com",
          "employeeId":"jean.normandy"
         },
        "budgetApprovers":[
          {
            "externalUserCUUID":"8002250890004822936",
            "employeeUuid":"210fe25f-e326-495c-847a-de333173f616",
            "id":"f779261d-77ce-4123-b739-d842ef6f104d",
            "name":"Jean Normandy",
            "email":"jean.normandy@xyz.com",
            "employeeId":"jean.normandy"
          }
        ],
        "budgetManagers":[
          {
            "externalUserCUUID":"1563846384638464842",
            "employeeUuid":"13a13839-68d6-4ee8-90e9-58604278aa8f",
            "id":"e2bae688-e000-464a-8728-e1362c94f172",
            "name":"Walter Gupta",
            "email":"walter.gupta@xyz.com",
            "employeeId":"walter.gupta"
          }
        ],
        "budgetType": "PERSONAL_USE",
        "budgetViewers":[
          {
            "externalUserCUUID":"5005380230004873464",
            "employeeUuid":"eb6082b0-3a9a-4e79-a350-e6e067f34969",
            "id":"7ce7dfe0-6168-4b93-bb35-386bf023acc6",
            "name":"Dan Lee",
            "email":"dan.lee@xyz.com",
            "employeeId":"dan.lee"
          }
        ],
        "dateRange": null,
        "fiscalYear":{
          "name":"2017",
          "displayName":"2017",
          "startDate":"2017-01-01",
          "endDate":"2017-12-31",
          "status":"OPEN",
          "id":"a4f9d57f-14ac-4f03-b5aa-4256e5cff790",
          "lastModified":"2017-03-26 20:53:19",
          "currentYear":false
        }
      },
    {"Additional budget item headers removed for brevity":"Additional budget items headers removed for brevity"}
  ],
  "href":"https://us.api.concursolutions.com/budget/v1.1/budgetItemHeader/?offset=0",
  "next":{
    "href":"http://budget-service-rqa3-budget.us-west-2.nonprod.cnqr.delivery/budget/v1.1/budgetItemHeader/?adminView=true&offset=50"
  },
  "previous":null
}









GET a Budget Item

Retrieve the details of a single budget item.

Scopes

This API call requires one of the following scopes:

Request

URI

GET  /budget/v4/budgetItemHeader/{id}

Template

Parameters

Name Type Format Description
id string uuid The budget item header's key field.

Headers

Response

Status Codes

Headers

Response Headers

Payload

Budget Item Header

Example

GET https://us.api.concursolutions.com/budget/v4/budgetItemHeader/72eee673-3d81-49c2-966a-b63c7a9302e6
Authorization: Bearer {token}

Request

HTTP/1.1 200 OK
Cache-Control: max-age=604800
Content-Type: application/json
Date: Wed, 06 Jul 2020 17:33:03 GMT
Etag: "359670651"
Expires: Wed, 13 Jul 2020 17:33:03 GMT
Last-Modified: Fri, 09 Aug 2020 23:54:35 GMT
Content-Length: 1270
concur-correlationid: 918cfb55-06a1-47da-8ef1-774a45427af9

Response

 {
    "name":"Marketing-US-Jean Normandy",
    "isTest":false,
    "budgetItemStatusType":"OPEN",
    "description":"Marketing-US",
    "id":"72eee673-3d81-49c2-966a-b63c7a9302e6",
    "costObjects":[
     {
          "code": "6",
          "fieldDefinitionId": "86eee673-3d81-49c2-966a-b63c7a9302e2",
          "value": "2",
          "listKey": "1334",
          "operator": "EQUAL",
          "displayName": "Country Code"
        }
    ],
    "periodType":"QUARTERLY",
    "active":true,
    "owned":false,
    "budgetAmounts":{
      "pendingAmount":6870.48165307,
      "unExpensedAmount":102126.89000000,
      "spendAmount":764.86966050,
      "adjustedBudgetAmount": 0,
      "availableAmount":2364.64868643,
      "unExpensedSettings":null,
      "threshold":"UNDER",
      "consumedPercent":76
    },
    "createdDate": "2019-06-26T17:49:53.102Z",
    "currencyCode":"EUR",
    "annualBudget":10000.00000000,
    "budgetCategory":null,
    "owner":{
      "externalUserCUUID":"8002250890004822936",
      "employeeUuid":"210fe25f-e326-495c-847a-de333173f616",
      "id":"f779261d-77ce-4123-b739-d842ef6f104d",
      "name":"Jean Normandy",
      "email":"jean.normandy@xyz.com",
      "employeeId":"jean.normandy"
     },
    "budgetApprovers":[
       {
        "externalUserCUUID":"8002250890004822936",
        "employeeUuid":"210fe25f-e326-495c-847a-de333173f616",
        "id":"f779261d-77ce-4123-b739-d842ef6f104d",
        "name":"Jean Normandy",
        "email":"jean.normandy@xyz.com",
        "employeeId":"jean.normandy"
       }
    ],
    "budgetManagers":[
      {
        "externalUserCUUID":"1563846384638464842",
        "employeeUuid":"13a13839-68d6-4ee8-90e9-58604278aa8f",
        "id":"e2bae688-e000-464a-8728-e1362c94f172",
        "name":"Walter Gupta",
        "email":"walter.gupta@xyz.com",
        "employeeId":"walter.gupta"
      }
    ],
    "budgetType": "PERSONAL_USE",
    "budgetViewers":[
      {
        "externalUserCUUID":"5005380230004873464",
        "employeeUuid":"eb6082b0-3a9a-4e79-a350-e6e067f34969",
        "id":"7ce7dfe0-6168-4b93-bb35-386bf023acc6",
        "name":"Dan Lee",
        "email":"dan.lee@xyz.com",
        "employeeId":"dan.lee"
      }
    ],
    "budgetItemDetails":[
      {
        "budgetItemHeaderId":"72eee673-3d81-49c2-966a-b63c7a9302e6",
        "budgetName":"Marketing-US-Jean Normandy",
        "currencyCode":"USD",
        "amount":2500.00000000,
        "id":"4c165d40-804f-4aaa-b900-a46538537f6a",
        "budgetItemDetailStatusType":"OPEN",
        "budgetAmounts":{
          "pendingAmount":6870.48165307,
          "unExpensedAmount":102126.89000000,
          "spendAmount":764.86966050,
          "adjustedBudgetAmount": 0,
          "availableAmount":-5135.35131357,
          "unExpensedSettings":null,
          "consumedPercent":305,
          "threshold":"OVER"
        },
        "detailDashboardBudgetItemAdjustmentDTOs": [
          {
            "adjustmentType": "BUDGET_BALANCE",
            "amount": 0,
            "amountType": "QUICK_EXPENSE",
            "description": "string",
            "transactionDate": "2019-06-26"
          }
        ],
        "fiscalPeriod":{
          "name":"2017 - Q1",
          "fiscalPeriodStatus":"OPEN",
          "id":"b9659f8a-4e74-4531-9e23-1222ab1507f2",
          "periodType":"QUARTERLY",
          "startDate":"2017-01-01",
          "endDate":"2017-03-31",
          "spendDate":null,
          "fiscalYearId":"bcb41c95-2d53-4a1a-830f-7c6b01fa79da",
          "currentPeriod":false
        },
        "budgetItemBalances":[
          {
            "featureTypeCode":"PURCHASE_REQUEST",
            "featureTypeSubCode":"NONE",
            "workflowState":"SUBMITTED",
            "amount":6870.48165307,
            "id":"11cb732e-cbc4-41cb-82be-162d632d5499"
          },
          {
            "featureTypeCode":"EXPENSE",
            "featureTypeSubCode":"NONE",
            "workflowState":"PAID",
            "amount":764.86966050,
            "id":"0f09cc65-b879-4969-a8a1-9dd52c96486d"
          },
          {
            "featureTypeCode":"EXPENSE",
            "featureTypeSubCode":"ERECEIPTS",
            "workflowState":"UNSUBMITTED",
            "amount":102126.89000000,
            "id":"27c49c8a-c24d-42eb-b089-84268350ae03"
          }
        ]
      },
      {
        "budgetItemHeaderId":"72eee673-3d81-49c2-966a-b63c7a9302e6",
        "budgetName":"Marketing-US-Jean Normandy",
        "currencyCode":"EUR",
        "amount":2500.00000000,
        "id":"0a2dc181-389e-4c85-bb57-e4f1a11ace4e",
        "budgetItemDetailStatusType":"OPEN",
        "budgetAmounts":{
          "pendingAmount":0,
          "unExpensedAmount":0,
          "spendAmount":0,
          "adjustedBudgetAmount": 0,
          "availableAmount":2500.00000000,
          "unExpensedSettings":null,
          "consumedPercent":0,
          "threshold":"UNDER"
        },
        "detailDashboardBudgetItemAdjustmentDTOs": [
          {
            "adjustmentType": "BUDGET_BALANCE",
            "amount": 0,
            "amountType": "QUICK_EXPENSE",
            "description": "string",
            "transactionDate": "2019-06-26"
          }
        ],
        "fiscalPeriod":{
          "name":"2017 - Q2",
          "fiscalPeriodStatus":"OPEN",
          "id":"590d4e22-40be-43cc-ac1b-01b0d0263e19",
          "periodType":"QUARTERLY",
          "startDate":"2017-04-01",
          "endDate":"2017-06-30",
          "spendDate":null,
          "fiscalYearId":"bcb41c95-2d53-4a1a-830f-7c6b01fa79da",
          "currentPeriod":true
        },
        "budgetItemBalances":[]
      },
      {
        "Additional budget item details removed for brevity": "Additional budget item details removed for brevity"
      }
    ],
    "dateRange": null,
    "fiscalYear":{
      "name":"2017",
      "displayName":"2017",
      "startDate":"2017-01-01",
      "endDate":"2017-12-31",
      "status":"OPEN",
      "id":"a4f9d57f-14ac-4f03-b5aa-4256e5cff790",
      "lastModified":"2017-03-26 20:53:19",
      "currentYear":false,
      "monthlyFiscalPeriods":[
        {
          "name":"2017-Special - Jan",
          "fiscalPeriodStatus":"OPEN",
          "periodType":"MONTHLY",
          "startDate":"2017-01-01",
          "endDate":"2017-01-31",
          "id":"1929d1d9-6c99-4635-9272-508364193f8f",
          "spendDate":null,
          "fiscalYearId":"2edd7bd4-8f10-46e5-bf52-d553f6c7df80",
          "currentPeriod":false
        },
        {
          "name":"2017-Special - Feb",
          "fiscalPeriodStatus":"OPEN",
          "periodType":"MONTHLY",
          "startDate":"2017-02-01",
          "endDate":"2017-02-28",
          "id":"41aa7452-e52a-4fd6-9c8a-5b199edeadaf",
          "spendDate":null,
          "fiscalYearId":"2edd7bd4-8f10-46e5-bf52-d553f6c7df80",
          "currentPeriod":false
        },
        {
          "name":"2017-Special - Mar",
          "fiscalPeriodStatus":"OPEN",
          "periodType":"MONTHLY",
          "startDate":"2017-03-01",
          "endDate":"2017-03-31",
          "id":"6c7d0b13-96b9-4d76-a083-4d38c96144e2",
          "spendDate":null,
          "fiscalYearId":"2edd7bd4-8f10-46e5-bf52-d553f6c7df80",
          "currentPeriod":false
        }
      ],
      "quarterlyFiscalPeriods":[
        {
          "name":"2017-Special - Q1",
          "fiscalPeriodStatus":"OPEN",
          "id":"5ce25dfd-8b2b-4fea-91eb-f8f9ad0bb896 ",
          "periodType":"QUARTERLY",
          "startDate":"2017-01-01",
          "endDate":"2017-03-31",
          "spendDate":null,
          "fiscalYearId":"2edd7bd4-8f10-46e5-bf52-d553f6c7df80",
          "currentPeriod":false
        },
        {
        "name":"2017-Special - Q2",
        "fiscalPeriodStatus":"OPEN",
        "id":"5ce25dfd-8b2b-4fea-91eb-f8f9ad0bb896 ",
        "periodType":"QUARTERLY",
        "startDate":"2017-04-01",
        "endDate":"2017-06-30",
        "spendDate":null,
        "fiscalYearId":"2edd7bd4-8f10-46e5-bf52-d553f6c7df80",
        "currentPeriod":false
      },
      {
        "name":"2017-Special - Q3",
        "fiscalPeriodStatus":"OPEN",
        "id":"5ce25dfd-8b2b-4fea-91eb-f8f9ad0bb896 ",
        "periodType":"QUARTERLY",
        "startDate":"2017-07-01",
        "endDate":"2017-09-30",
        "spendDate":null,
        "fiscalYearId":"2edd7bd4-8f10-46e5-bf52-d553f6c7df80",
        "currentPeriod":false
      },
      {
        "name":"2017-Special - Q4",
        "fiscalPeriodStatus":"OPEN",
        "id":"5ce25dfd-8b2b-4fea-91eb-f8f9ad0bb896 ",
        "periodType":"QUARTERLY",
        "startDate":"2017-10-01",
        "endDate":"2017-12-31",
        "spendDate":null,
        "fiscalYearId":"2edd7bd4-8f10-46e5-bf52-d553f6c7df80",
        "currentPeriod":false
      }
      ],
      "yearlyFiscalPeriods":[
        {
          "name":"2017-Special",
          "fiscalPeriodStatus":"OPEN",
          "id":"a6bede66-4f3d-412f-a620-2a073013cb2a",
          "periodType":"YEARLY",
          "startDate":"2017-01-01",
          "endDate":"2017-12-31",
          "spendDate":null,
          "fiscalYearId":"2edd7bd4-8f10-46e5-bf52-d553f6c7df80",
          "currentPeriod":false
        }
      ],
      "customFiscalPeriods":[],
    }
  }





POST a Budget Item

Save a new budget or update an existing budget.

Scopes

budgetitem.write - Refer to Scope Usage for full details.

Request

URI

Template

POST  /budget/v4/budgetItemHeader

Parameters

N/A

Headers

Payload

Budget Item Header

Response

Status Codes

Headers

Response Headers

Payload

Budget Item Response or Error Response

Example

POST https://us.api.concursolutions.com/budget/v4/budgetItemHeader
Authorization: Bearer {token}

Request

Quarterly Budget Example

  {
    "name":"Marketing-US-Jean Normandy",
    "isTest":false,
    "budgetItemStatusType":"OPEN",
    "description":"Marketing-US",
    "id":"72eee673-3d81-49c2-966a-b63c7a9302e6",
    "costObjects":[
      {
      "fieldDefinitionId":"86eee673-3d81-49c2-966a-b63c7a9302e2",
      "code": "6",
      "value": "2",
      "listKey": "1334",
      "operator": "EQUAL",
      "displayName":"Country Code"
    }
    ],
    "periodType":"QUARTERLY",
    "currencyCode":"EUR",
    "budgetCategory":{
      "id":"27451c2d-9121-44bd-b4b0-f2119d2071c7"
    },
    "owner":{
      "externalUserCUUID":"8002250890004822936",
      "employeeUuid":"210fe25f-e326-495c-847a-de333173f616",
      "email":"jean.normandy@xyz.com",
      "employeeId":"jean.normandy"
     },
    "budgetApprovers":[
      {
        "externalUserCUUID":"5005380230004873464",
        "employeeUuid":"eb6082b0-3a9a-4e79-a350-e6e067f34969",
        "email":"dan.lee@xyz.com",
        "employeeId":"dan.lee"
      }
    ],
    "budgetManagers":[
      {
        "externalUserCUUID":"1563846384638464842",
        "employeeUuid":"13a13839-68d6-4ee8-90e9-58604278aa8f",
        "email":"walter.gupta@xyz.com",
        "employeeId":"walter.gupta"
      }
    ],
    "budgetType": "PERSONAL_USE",
    "budgetViewers":[
      {
        "externalUserCUUID":"5005380230004873464",
        "employeeUuid":"eb6082b0-3a9a-4e79-a350-e6e067f34969",
        "email":"dan.lee@xyz.com",
        "employeeId":"dan.lee"
      }
    ],
    "budgetItemDetails":[
      {
        "budgetItemHeaderId":"72eee673-3d81-49c2-966a-b63c7a9302e6",
        "budgetName":"Marketing-US-Jean Normandy",
        "currencyCode":"EUR",
        "amount":2500.00000000,
        "id":"4c165d40-804f-4aaa-b900-a46538537f6a",
        "budgetItemDetailStatusType":"OPEN",
        "fiscalPeriod":{
          "id":"b9659f8a-4e74-4531-9e23-1222ab1507f2"
        }
      },
      {
        "budgetItemHeaderId":"72eee673-3d81-49c2-966a-b63c7a9302e6",
        "budgetName":"Marketing-US-Jean Normandy",
        "currencyCode":"EUR",
        "amount":2500.00000000,
        "id":"0a2dc181-389e-4c85-bb57-e4f1a11ace4e",
        "budgetItemDetailStatusType":"OPEN",
        "fiscalPeriod":{
          "id":"590d4e22-40be-43cc-ac1b-01b0d0263e19"
        }
      },
      {
        "budgetItemHeaderId":"72eee673-3d81-49c2-966a-b63c7a9302e6",
        "budgetName":"Marketing-US-Jean Normandy",
        "currencyCode":"EUR",
        "amount":2500.00000000,
        "id":"35d7dc8a-5ec8-4d5f-ba7c-d9304f7afee3",
        "budgetItemDetailStatusType":"OPEN",
        "fiscalPeriod":{
          "id":"09cd5be1-a21d-47f2-b6b5-8d9019709327"
        }
      },
      {
        "budgetItemHeaderId":"72eee673-3d81-49c2-966a-b63c7a9302e6",
        "budgetName":"Marketing-US-Jean Normandy",
        "currencyCode":"EUR",
        "amount":2500.00000000,
        "id":"4ec30f7c-e7fa-4832-9134-85bed9a85b9c",
        "budgetItemDetailStatusType":"OPEN",
        "fiscalPeriod":{
          "id":"c3beec03-a096-4a33-b7af-b49127742702"
        }
      }
    ],
    "fiscalYear":{
      "id":"a4f9d57f-14ac-4f03-b5aa-4256e5cff790"
    }
  }

Date Range Budget Example

  {
    "name":"Marketing-US-Jean Normandy Date Range",
    "isTest":false,
    "budgetItemStatusType":"OPEN",
    "description":"Marketing-US",
    "id":"72eee673-3d81-49c2-966a-b63c7a9302e6",
    "costObjects":[
     {
      "code": "6",
      "fieldDefinitionId": "86eee673-3d81-49c2-966a-b63c7a9302e2",
      "value": "2",
      "listKey": "1334",
      "operator": "EQUAL",
      "displayName": "Country Code"
    }
    ],
    "periodType":"DATE_RANGE",
    "currencyCode":"EUR",
    "budgetCategory":{
      "id":"27451c2d-9121-44bd-b4b0-f2119d2071c7"
    },
    "owner":{
      "externalUserCUUID":"8002250890004822936",
      "employeeUuid":"210fe25f-e326-495c-847a-de333173f616",
      "email":"jean.normandy@xyz.com",
      "employeeId":"jean.normandy"
     },
    "budgetApprovers":[
      {
        "externalUserCUUID":"5005380230004873464",
        "employeeUuid":"eb6082b0-3a9a-4e79-a350-e6e067f34969",
        "email":"dan.lee@xyz.com",
        "employeeId":"dan.lee"
      }
    ],
    "budgetManagers":[
      {
        "externalUserCUUID":"1563846384638464842",
        "employeeUuid":"13a13839-68d6-4ee8-90e9-58604278aa8f",
        "email":"walter.gupta@xyz.com",
        "employeeId":"walter.gupta"
      }
    ],
    "budgetType": "PERSONAL_USE",
    "budgetViewers":[
      {
        "externalUserCUUID":"5005380230004873464",
        "employeeUuid":"eb6082b0-3a9a-4e79-a350-e6e067f34969",
        "email":"dan.lee@xyz.com",
        "employeeId":"dan.lee"
      }
    ],
    "budgetItemDetails":[
      {
        "budgetItemHeaderId":"72eee673-3d81-49c2-966a-b63c7a9302e6",
        "budgetName":"Marketing-US-Jean Normandy",
        "currencyCode":"EUR",
        "amount":2500.00000000,
        "id":"4c165d40-804f-4aaa-b900-a46538537f6a",
        "budgetItemDetailStatusType":"OPEN",
        "fiscalPeriod":{
          "id":"b9659f8a-4e74-4531-9e23-1222ab1507f7"
        }
      }
    ],
    "fiscalYear":{
      "id":null
    }
  }

Response

Success Response

HTTP/1.1 200 OK
Cache-Control: max-age=604800
Content-Type: application/json
Date: Wed, 06 Jul 2020 17:33:03 GMT
Etag: "359670651"
Expires: Wed, 13 Jul 2020 17:33:03 GMT
Last-Modified: Fri, 09 Aug 2020 23:54:35 GMT
Content-Length: 97
concur-correlationid: 809a0898-e523-4114-950d-bd22705a3b25
  {
    "success": true,
    "budgetItemHeaderId": "72eee673-3d81-49c2-966a-b63c7a9302e6"
  }

Failure Response

HTTP/1.1 400 Bad Request
Cache-Control: no-store
Connection: close
Content-Length: 459
Content-Type: application/json;charset=utf-8
Date: Fri, 21 Sep 2018 15:27:05 GMT
Expires: Thu, 20 Sep 2018 15:27:05 GMT
Pragma: no-cache
concur-correlationid: cea62849-02e5-4a7f-a576-68280c84bd02
{
  "status" : false,
  "errorMessageList" : [
    {
      "errorType" : "ERROR",
      "errorCode" : "BUDGET.BUDGET_ITEM_NAME_REQUIRED",
      "errorMessage" : "Budget item name is required"
    },
    {
      "errorType" : "ERROR",
      "errorCode" : "BUDGET.BUDGET_ITEM_NAME_ERROR",
      "errorMessage" : "Budget item name should be more than 1 characters"
    },
    {
      "errorType" : "ERROR",
      "errorCode" : "BUDGET.BUDGET_ITEM_OWNER_REQUIRED",
      "errorMessage" : "Budget item owner is required"
    }
  ]
}

DELETE a Budget Item Header

Delete a budget item.

Scopes

budgetitem.write - Refer to Scope Usage for full details.

Request

URI

Template

DELETE  /budget/v4/budgetItemHeader/{id}

Parameters

Name Type Format Description
id string path The budget item header's key field.

Headers

Response

Status Codes

Headers

Response Headers

Payload

Budget Item Response or Error Response

Example

Request

DELETE https://us.api.concursolutions.com/budget/v4/budgetItemHeader/72eee673-3d81-49c2-966a-b63c7a9302e6
Authorization: Bearer {token}

Response

HTTP/1.1 200 OK
Cache-Control: no-store
Connection: keep-alive
Content-Length: 97
Content-Type: application/json;charset=utf-8
Date: Fri, 21 Sep 2018 15:24:27 GMT
Expires: Thu, 20 Sep 2018 15:24:27 GMT
Pragma: no-cache
Vary: Origin
concur-correlationid: 86a0d9fe-9e98-43c3-89d8-a2917dd844cb
  {
    "success": true,
    "budgetItemHeaderId": "72eee673-3d81-49c2-966a-b63c7a9302e6"
  }

Budget Item - Schema

PagedBudgetItemHeaderList

Name Type Format Description
totalRows integer - The total number of rows available.
offset integer - The starting row for this page of results (zero-based).
limit integer - The number of results returned per page. Maximum: 50
budgetItemHeaders array budgetItemHeader List of budget item headers. Each budget item header represents a single budget for a fiscal year.
href string - The link to this page of results.
previous string href The href for the previous page of results (null if this is the first page of results).
next string href The href for the next page of results (null if no results remaining).

BudgetItemHeader

Name Type Format Description
active boolean - READ ONLY Indicates if this budget should be displayed on user screens.
annualBudget decimal - READ ONLY The total budget amount and accumulated balances for this budget header.
budgetAmounts array budgetAmounts READ ONLY The accumulated budget amounts for this budget.
budgetManagers array budgetPerson If managers exist, spend items only matches this budget if one of the managers is in the manager hierarchy of the submitter or approver for the given spend item.
budgetApprovers array budgetPerson The workflow approvers for this budget.
budgetCategory array budgetCategory The budget category for this budget item. If a budget category is present, spending items must match one of the expense types in the budget category in order to match this budget.
budgetItemDetails array budgetItemDetail Required Specify the budget information for each fiscal period in the fiscal year.
budgetItemStatusType string - The status of this budget item. Supported values: OPEN, CLOSED(no spending can be attached to this budget), REMOVED
budgetType string - The budget type indicates if the budget item is personal or not. Supported values: PERSONAL_USE, BUDGET, RESTRICTED
budgetViewers array budgetPerson The users who can view this budget.
costObjects array budgetTrackingValue The cost object list for matching spending items.
createdDate date YYYY-MM-DD READ ONLY The time the budget item header was created. Date in UTC.
currencyCode string - The 3-letter ISO 4217 currency code for the budget currency. This is the currency code of the budget amount. Spending Items are converted using yesterday's closing value. Examples: USD - US dollars; BRL - Brazilian real; CAD - Canadian dollar; CHF - Swiss franc; EUR - Euro; GBO - Pound sterling; HKD - Hong Kong dollar; INR - Indian rupee; MXN - Mexican peso; NOK - Norwegian krone; SEK - Swedish krona.
description string - Required The user-friendly name for this budget. This description is displayed to end users on desktop and mobile.
dateRange dateRange - READ ONLY Specify custom date range for budget.
fiscalYear array fiscalYear Required The fiscal year for this budget. Only the ID of the fiscal year, which can be retrieved from the Fiscal Year service, is required for creating/updating a budget.
fiscalYearId string - The unique identifier of the fiscal year for this budget.
id string - The key for this object.
isTest boolean - The test flag for the budget item. If true, this budget will only match spending submitted by test users.
lastModifiedDate dateRange - READ ONLY The last time the budget item header was updated. Date in UTC.
name string - Required The admin-facing name for this budget.
owned string - READ ONLY A flag indicating if the current user is the owner of this budget.
owner array budgetPerson Required The user who is ultimately responsible for this budget.
periodType string - READ ONLY The type of period within the fiscal year that this budget's details use.

BudgetItemDetail

Name Type Format Description
amount decimal - Required The budget currency amount allocated to this fiscal period. May be zero.
budgetAmounts array budgetAmounts READ ONLY The accumulated budget numbers for this budget.
budgetItemBalances array budgetItemBalance READ ONLY Shows the break-out of budget spending by product and workflow state.
budgetItemDetailStatusType string - The status of this budget item. Supported values: OPEN, CLOSED(no spending can be attached to this budget), REMOVED
currencyCode string - The 3-letter ISO 4217 currency code for the budget currency. Examples: USD - US dollars; BRL - Brazilian real; CAD - Canadian dollar; CHF - Swiss franc; EUR - Euro; GBO - Pound sterling; HKD - Hong Kong dollar; INR - Indian rupee; MXN - Mexican peso; NOK - Norwegian krone; SEK - Swedish krona.
budgetName string - READ ONLY The admin-facing name of this budget.
budgetItemHeaderId string - READ ONLY The unique ID of the header that contains this budget item detail.
fiscalPeriod fiscalPeriod - Required The fiscal period for this budget amount. Only the ID of the fiscal period, which can be retrieved from the Fiscal Year service, is required for creating/updating a budget.
detailDashboardBudgetItemAdjustmentDTOs array detailDashboardBudgetItemAdjustment READ ONLY List of budget adjustments.
fiscalPeriod array fiscalPeriod Required The specific fiscal period when this budget amount will be used. Only the ID of the fiscal period, which can be retrieved from the Fiscal Year service, is required for creating/updating a budget.

BudgetAmounts

Name Type Format Description
adjustedBudgetAmount decimal - READ ONLY The amount adjusted against this budget.
availableAmount decimal - READ ONLY The available amount accumulated against this budget. Uses budget setting to determine which amounts are included to calculate available amount.
consumedPercent decimal - READ ONLY The percentage of the budget that is considered used. Uses budget setting to determine which amounts to include.
pendingAmount decimal - READ ONLY The pending amount accumulated against this budget.
spendAmount decimal - READ ONLY The spent amount accumulated against this budget.
threshold string - READ ONLY The indicator of whether this budget is under the alert limit, equal to or over the alert limit but under the control limit, or equal to or over the control limit. Supported values: UNDER, ALERT, OVER
unExpensedAmount decimal - READ ONLY The amount of unexpensed items like travel bookings, quick expenses, or e-receipts.
unExpensedSettings string - READ ONLY The company's budget setting for unexpensed items. Applies to all budgets for the company. Supported values: SHOW_UNSUBMITTED_EXPENSES_AS_PENDING, SHOW_UNSUBMITTED_EXPENSES_BALANCE, DO_NOT_SHOW_UNSUBMITTED_EXPENSES

BudgetPerson

Provide externalUserCUUID or email or employee ID of the user for looking up the person.

Name Type Format Description
externalUserCUUID string - The unique identifier for this user. This must match the CUUID from SAP Concur's profile service.
name string - READ ONLY The user's name. Provided for convenience.
id string - The budget service's unique identifier for this user.
email string - The email address of the person to lookup.
employeeId string - READ ONLY The employee ID of the person to lookup.
employeeUuid string - The unique identifier for this user. This must match the UUID from SAP Concur's profile service.

BudgetCategory

Name Type Format Description
description string - The list of expense types that this budget category matches.
name string - The admin-facing name for this category.
statusType string - The status of this budget category. Supported values: OPEN, REMOVED
id string - The unique identifier for the budget category.

ExpenseType

Name Type Format Description
featureTypeCode string - Required The product that this expense type applies to: Purchase Request, Invoice (Payment Request), Expense, or Request. Supported values: PURCHASE_REQUEST, PAYMENT_REQUEST, EXPENSE, REQUEST
expenseTypeCode string - Required The alphanumeric code that describes an expense type. (Example: MEALS, AC_CATER) Valid expense type codes are returned by the GET /budgetCategory/expenseType method described in the Budget Category service.
name string - READ ONLY The name for this expense type if it maps to an expense type set up in your SAP Concur product(s).
id string - The budget service's key for this object.

BudgetTrackingValue

Name Type Format Description
code string - The code for the cost object field. This can be used instead of fieldDefinitionId and will take priority if populated. This value can be found for your budget tracking fields you have configured by using the GET All Budget Tracking Fields resource.
value string - The value for the cost object field. The value of this field will be ignored unless the operator field is EQUAL, NOTEQUAL, INLIST, or NOTINLIST. The value of this field can be one or more comma-separated values if the INLIST or NOTINLIST operator is chosen.
listKey string - When setting up the budget, specify the listKey that maps to the value of this list in the SAP Concur list service.
operator string - Required The comparison to use when matching values for this tracking field. Supported values: EQUAL, INLIST, ISBLANK, NOTEQUAL, NOTINLIST, ISNOTBLANK, ISTRUE, ISFALSE, ISNOTTRUE, ISNOTFALSE
fieldDefinitionID string - Required The budget service’s key for this object’s field definition ID. This value can be found for your budget tracking fields you have configured by using the GET All Budget TrackingFields resource.
displayName string - The budget field tracking name.

BudgetItemBalance

Name Type Format Description
amount decimal - READ ONLY The balance amount.
featureTypeCode string - READ ONLY The product type for this balance. Supported values: REQUEST, TRAVEL, EXPENSE, PAYMENT_REQUEST
featureTypeSubCode string - READ ONLY The feature type sub code for this balance. Supported values: QUICK_EXPENSE, ERECEIPT, CREDIT_CARD, PERSONAL_CARD, TRIP, RECEIPT_CAPTURE, BILLING_STATEMENT, MANUAL, NONE, BUDGET_AMOUNT, SPENT_AMOUNT, PENDING_AMOUNT, PRE_AUTHORIZED, PURGE_ADJUSTMENT
workflowState string - READ ONLY Supported values: UNSUBMITTED, UNSUBMITTED_HELD, SUBMITTED, APPROVED, PROCESSED, PAID.
id string - The unique identifier for this particular budget balance bucket..

Budget Item - FiscalYear

Name Type Format Description
currentYear boolean - READ ONLY If true, this is the current fiscal year based on the current date and time. false, if otherwise.
startDate date YYYY-MM-DD Required The start date for this fiscal year. The distance between start date and end date may not be more than two years.
endDate date YYYY-MM-DD Required The end date for this fiscal year. The distance between start date and end date may not be more than two years.
name datetime - Required The name of this fiscal year. Must be unique for this entity.
status string - Required The status of this fiscal year. Supported values: OPEN, CLOSED, REMOVED
id string - The budget service's key for this object.
lastModified datetime - READ ONLY The UTC date and time when this object was last changed.
displayName string - READ ONLY Display name for fiscal year. For date range budget item we use this field to display.
monthlyFiscalPeriods array fiscalPeriod READ ONLY The list of monthly Fiscal Periods in this Fiscal Year. Fiscal periods must complete fill the parent Fiscal Year with no overlaps.
quarterlyFiscalPeriods array fiscalPeriod READ ONLY The list of quarterly Fiscal Periods in this Fiscal Year. If this parameter is not specified, quarterly Fiscal Periods are automatically generated based on the monthly Fiscal Periods supplied.
yearlyFiscalPeriods array fiscalPeriod READ ONLY The list of yearly Fiscal Periods in this Fiscal Year. If this parameter is not specified, one period is created that fills the Fiscal Year.
customFiscalPeriods array fiscalPeriod READ ONLY The list of custom Fiscal Periods in this Fiscal Year. Custom Fiscal Periods are API-only and will not display on user budget dashboards.
openAndClosedFiscalPeriods array fiscalPeriod READ ONLY The list of all Fiscal Periods in this Fiscal Year, sorted by status.
fiscalPeriods array fiscalPeriod READ ONLY The list of all Fiscal Periods in this Fiscal Year.
displayName string - READ ONLY Display name for fiscal year. For date range budget item we use this field to display.

Budget Item - FiscalPeriod

Name Type Format Description
currentPeriod boolean - READ ONLY If true, this is the current fiscal period based on the current time. false, if otherwise.
startDate date YYYY-MM-DD Required The start date for this fiscal period. Must be within the parent fiscal year.
endDate date YYYY-MM-DD Required The end date for this fiscal year. Must be within the parent fiscal year.
name string - Required The name of this fiscal period. Must be unique for this entity.
fiscalPeriodStatus string - Required The status of this fiscal period. Supported values: OPEN, CLOSED, REMOVED
periodType string - Required The type of fiscal period. Supported values: MONTHLY, QUARTERLY, YEARLY, CUSTOM, DATE_RANGE
fiscalYearId string - The key of the parent fiscal year for this fiscal period.
id string - The budget service's key for this object.
spendDate date - READ ONLY If the current date is after this fiscal period's start date, this field shows the current date.

DateRange

Name Type Format Description
startDate date YYYY-MM-DD The start date for the budget.
endDate date YYYY-MM-DD The end date for the budget.

DetailDashboardBudgetItemAdjustment

Name Type Format Description
adjustmentType string - The type of adjustment being made. Only a user reference field. Supported values: BUDGET_BALANCE, FUND_TRANSFER, EXPENSE, PAYMENT_REQUEST, PURCHASE_REQUEST, REQUEST, PURGE_ADJUSTMENT
amount decimal - The value of the amount adjusted (+/-).
amountType string - The amount type of the field. Supported values: QUICK_EXPENSE, ERECEIPT, CREDIT_CARD, PERSONAL_CARD, TRIP, RECEIPT_CAPTURE, BILLING_STATEMENT, MANUAL, NONE, BUDGET_AMOUNT, SPENT_AMOUNT, PENDING_AMOUNT, PRE_AUTHORIZED, PURGE_ADJUSTMENT
description string - The short description of the adjustment.
transactionDate date YYYY-MM-DD The transaction date of adjusted spend. Required when the adjustment is made for amount type. Supported values: SPENT_AMOUNT, PENDING_AMOUNT

BudgetItemResponse

Name Type Format Description
success boolean - True or False for success or failure.
budgetItemHeaderId guid - The key of the created/updated/removed budget item header.

Budget Item - Error Response

Name Type Format Description
status boolean - False if there was an error.
errorMessageList array errorMessage List of all errors detected.

Budget Item - Error Message

Name Type Format Description
errorType String - WARNING or ERROR.
errorCode String - Text code for this error.
errorMessage String - Plain language error message.

Budget Item - Response Headers

Budget v4 - Budget Tracking

This resource is used to retrieve information about Budget's tracking fields for an entity. Every entity may have a specific set of budget tracking fields and every budget may enable any or all of the budget tracking fields. If there are tracking fields associated, the budgets get matched to the product only when the tracking field conditions are met.

GET All Budget Tracking Fields

Retrieve budget tracking fields information that is setup in budget configuration. This information returned here like the field definition ID, is needed if you will be importing budgets with tracking field values using the post budget item resource.

Scopes

This API call requires one of the following scopes:

Request

URI

GET /budget/v4/budgetTrackingField

Template

Parameters

N/A

Headers

Response

Status Codes

Headers

Payload

Budget Tracking Field

Example

GET https://us.api.concursolutions.com/budget/v4/budgetTrackingField
Authorization: Bearer {token}
Content-Type: application/json
Accept: application/json

Request

HTTP/1.1 200 OK
Cache-Control: no-store
Connection: keep-alive
Content-Length: 1371
Content-Type: application/json;charset=utf-8
Date: Fri, 21 Sep 2018 15:24:27 GMT
Expires: Thu, 20 Sep 2018 15:24:27 GMT
Pragma: no-cache
Vary: Origin
concur-correlationid: 86a0d9fe-9e98-43c3-89d8-a2917dd844cb

Response

[
   {
        "budgetTrackingFieldName": "Cost Center",
        "fieldType": "LIST",
        "listSyncGuid": "8652CDF9C12B4051B8D180E20840CE9B",
        "fieldId": "86309e0c-913c-47a5-9bcf-24a05342c718",
        "budgetSequenceNumber": 2,
        "connectedListSequenceNumber": 1,
        "fieldDefinitionId":"19b07cff-4d36-44bd-acfe-befcfa607075"
    },
    {
        "budgetTrackingFieldName": "Company",
        "fieldType": "VARCHAR",
        "listSyncGuid": null,
        "fieldId": "d8f911a1-f298-4c65-b06b-710d482c9c46",
        "budgetSequenceNumber": 1,
        "connectedListSequenceNumber": 1,
        "fieldDefinitionId":"ea2b82f3-ac18-4509-a748-842054f47f5f"
    },
    {
        "budgetTrackingFieldName": "Department",
        "fieldType": "LIST",
        "listSyncGuid": "8652CDF9C12B4051B8D180E2084Q412",
        "fieldId": "c4f721cb-8fc9-48cf-993e-5ea0edefcdbd",
        "budgetSequenceNumber": 3,
        "connectedListSequenceNumber": 1,
        "fieldDefinitionId":"8b09cc4a-0274-4f2e-b223-3179f560c6bf"
    },
    {
        "budgetTrackingFieldName": "Vendor",
        "fieldType": "VARCHAR",
        "listSyncGuid": null,
        "fieldId": "bcc7ba39-a3a0-4267-84f4-1d5b439cce65",
        "budgetSequenceNumber": 5,
        "connectedListSequenceNumber": 1,
        "fieldDefinitionId":"d543d38a-ef64-4585-8151-b2f909b7e2d3"
    },
    {
        "budgetTrackingFieldName": "Region",
        "fieldType": "MLIST",
        "listSyncGuid": "8652CDF9C12B4051B8D180E20840CE9B",
        "fieldId": "a2502b74-e3ce-4b30-a3a4-b6ceb68cf677",
        "budgetSequenceNumber": 6,
        "connectedListSequenceNumber": 1,
        "fieldDefinitionId":"51c46189-110b-4de4-80ac-4cbae48625d6"
    },
    {
        "budgetTrackingFieldName": "Country",
        "fieldType": "VARCHAR",
        "listSyncGuid": null,
        "fieldId": "4ac122ad-8c0b-4076-bd41-49b09d576d5b",
        "budgetSequenceNumber": 4,
        "connectedListSequenceNumber": 1,
        "fieldDefinitionId":"b5017eae-0b99-47df-8e0d-2f908292598a"
    }
]

Budget Tracking - Schema

Budget Tracking Field

Name Type Format Description
budgetTrackingFieldName string - The budget field tracking name.
fieldType string - The data type of this field or field collection. Supported values: LIST, MLIST, VARCHAR
listSyncGuid string - If the dataType of this item is LIST or MLIST, this is the ID of the list definition from SAP Concur's list service.
fieldId string - The budget service's key for this object.
budgetSequenceNumber integer - The sequence or the order in which the budget tracking field appears in the budget UI. This value can be used instead of fieldDefinitionId when importing budgets with POST resource. The budgetSequenceNumber is the the same as the code field when importing budgets.
connectedListSequenceNumber integer - READ ONLY Indicates the level of the budget tracking field in a connected list.
fieldDefinitionId string - The budget service's key for this object's field definition ID. This value is required when using the Budget Item POST Resource to create or update a new budget using budget tracking fields.

Budget v4 - Budget Adjustments

This resource is used to add budget adjustments. Each budget item detail may have one or more budget adjustments and adjustments can be made to manually add or subtract the budget, spent or pending balances.

Create a Budget Adjustment

Create one or more budget adjustments.

Scopes

budgetitem.write - Refer to Scope Usage for full details.

Request

URI

POST /budget/v4/adjustments

Template

Parameters

Name Type Format Description
useMonthlyRollingUpdate boolean query Required If true, all adjustments for a given month, adjustment type, amount type & description will be rolled up to one adjustment. This is useful for an automated process that makes daily or weekly updates and doesn't want to clutter end-user dashboards.

Headers

Payload

Budget Adjustments

Response

Status Codes

Headers

Payload

Either "Success" or an Error Response

Example

POST https://us.api.concursolutions.com/budget/v4/adjustments?useMonthlyRollingUpdate=false
Authorization: Bearer {token}
Content-Type: application/json
Accept: application/json

Request

[
    {
        "budgetItemName":"API Budget-Oregon",
        "fiscalYearName": "2018",
        "budgetOwnerEmail": "m.jones@example.com",
        "fiscalPeriodName": "2018 - Q3",
        "amount": 100,
        "adjustmentType": "FUND_TRANSFER",
        "amountType": "BUDGET_AMOUNT",
        "description": "Initial July Adjustment",
        "transactionDate": "2018-07-11"
    },
    {
        "budgetItemName":"API Budget-Travel",
        "fiscalYearName": "2018",
        "budgetOwnerEmail": "m.jones@example.com",
        "fiscalPeriodName": "2018 - Q3",
        "amount": 100,
        "adjustmentType": "EXPENSE",
        "amountType": "SPENT_AMOUNT",
        "transactionDate": "2018-07-10"
    }
]

Response

Success Response

HTTP/1.1 200 OK
Cache-Control: no-store
Connection: keep-alive
Content-Length: 9
Content-Type: application/json;charset=utf-8
Date: Fri, 21 Sep 2018 15:24:27 GMT
Expires: Thu, 20 Sep 2018 15:24:27 GMT
Pragma: no-cache
Vary: Origin
concur-correlationid: 86a0d9fe-9e98-43c3-89d8-a2917dd844cb
"Success"

Failure Response

HTTP/1.1 400 Bad Request
Cache-Control: no-store
Connection: close
Content-Length: 242
Content-Type: application/json;charset=utf-8
Date: Fri, 21 Sep 2018 15:29:05 GMT
Expires: Thu, 20 Sep 2018 15:29:05 GMT
Pragma: no-cache
concur-correlationid: 561ce34c-6542-4bae-82a2-aa6ccd8c6b22
{
    "message": {  
        "status" : false,
        "errorMessageList" : [
          {
            "errorType" : "ERROR",
            "errorCode" : "BUDGET.BUDGET_PERIOD_REQUIRED",
            "errorMessage" : "Record 1) Record 1) Budget period is missing"
          }
        ]
    }
}

Budget Adjustments - Schema

Budget Adjustment

Name Type Format Description
budgetItemName string - Required The name of the budget of the adjustment.
fiscalYearName string - Required The name of the budget’s fiscal year. The default name for a fiscal year is the numeric, four-digit year. Example: 2019
fiscalPeriodName string - Required The specific fiscal period when this budget amount will be used. The default name for a fiscal period is: Monthly: <fiscal year name> - <three-letter month abbreviation> (Example: 2019 - Jun). Quarterly: <fiscal year name> - Q<number of quarter> (Example: 2019 - Q2). Yearly: <fiscal year name> (Example: 2019).
budgetOwnerEmail string - Required The user who is responsible for the budget, as configured.
amount decimal - Required The budget currency amount to be adjusted. The amount may be a positive or negative value but it cannot be zero.
adjustmentType string - Required The type of adjustment being made. Only a user reference field. Supported values: BUDGET_BALANCE, FUND_TRANSFER, EXPENSE, PAYMENT_REQUEST, PURCHASE_REQUEST, REQUEST
amountType string - Required The type of the budget’s balance to adjust. Affects which values in the budget are updated. Supported values: BUDGET_AMOUNT, SPENT_AMOUNT, PENDING_AMOUNT
description string - A user-friendly description of the adjustment.
transactionDate date YYYY-MM-DD Required if amount type is either SPENT_AMOUNT or PENDING_AMOUNT The transaction date of adjusted spend. Must be within the fiscal period.

Budget Adjustments - Error Response

Name Type Format Description
status boolean - False if there was an error.
errorMessageList array errorMessage List of all errors detected.

Budget Adjustments - Error Message

Name Type Format Description
errorType string - WARNING or ERROR.
errorCode string - Text code for this error.
errorMessage string - Plain language error message.

Callouts

Callouts and Application Connectors

Callouts - Overview

Callouts from SAP Concur allow clients to add an interaction with an outside system to their users' SAP Concur experience. The callouts require a web application, called an application connector, which SAP Concur will contact when appropriate. Application connectors can be hosted on the client's site or on a third-party hosting site.

Third-party developers can create callouts to provide SAP Concur clients access to information systems they manage. These developers partner with SAP Concur to have their application connectors reviewed. Once reviewed, applications are available for SAP Concur clients to purchase and configure.

Partner apps that want to use callout services must have their endpoint server(s) whitelisted with SAP Concur.

The available callouts are:

Fetch Attendee and Fetch List Item send information out from SAP Concur to an application connector that interfaces with a external system. The connector runs a search on the external system. The results are then returned to SAP Concur, which presents the results to the user.

The Event Notification callout allows clients to receive notification of specific moments in the workflow of an expense report. When a report enters the desired workflow state a request is sent to the external system. The system can call into SAP Concur to get all the details of a report and perform appropriate actions.

The Launch External URL callout gives clients and developers a platform to extend the functionality of SAP Concur, providing a means to deliver custom user interactions, or access functionality found in an external system.

The client can arrange to add an Expense Entry form field that is configured to use the Launch External URL callout to a Concur Expense Entry form. Concur Expense will display this field with an attached button that launches a separate window when clicked. The window is controlled by an application connector, created by the client, a third party developer, or SAP Concur. The application connector is a web server that presents information in the window.

The application connector can access SAP Concur data through the web services, or can access data in an external system. Once the user has completed their actions in the window (such as performing a search or completing a wizard), he/she clicks a button such as "Done" that indicates he/she has concluded their work in the window. The application connector then closes the window.

The application connector can use web services to send information to SAP Concur, to update field values on the expense entry form or other form types. The application connector may send the updates before or after the user closes the window. When the user returns to SAP Concur, the page refreshes and the user sees the current values.

Callouts - Process Flow

A process flow diagram showing flow between SAP Concur and an application connector

Application Connector Management

SAP Concur administrators use the Manage Application Connectors link on the Web Services page under Administration to register, test and enable application connectors.

Specifications

Security

SAP Concur will make calls to the application connector's endpoint using SSL. During configuration, SAP Concur will connect to the application connector to validate that its hostname and access credentials are valid.

SAP Concur will not be able to connect to the application connector until a certificate signed by a Certificate Authority (CA) is installed in the application connector. If you are hosting the application connector, you will need to install the signed certificate before SAP Concur can access the connector.

Callouts - Authentication

Authenticating to the application connector

Expense passes credentials using HTTP Basic Auth to authenticate with the application connector. By default, these credentials are stored in the appropriate web configuration file for your platform, such as web.xml or web.config. The steps to configure Expense with the credentials are detailed below.

Managing Application Connectors

SAP Concur administrators use the Manage Application Connectors link in Web Services under Administration to register, test and enable application connectors.

User Permission

The Web Services links can be accessed by users with the following permission:

Developer Sandbox or Expense/Invoice/Travel/Travel Request Standard:

Can Administer: Users with this permission can register and modify application connectors.

Expense/Invoice/Travel/Travel Request Professional:

Web Services Administrator: Users with this permission at companies that are Development Partners can register and modify application connectors.

All Admin roles: Users with this permission at companies that are Development Partners can register and modify application connectors.

Accessing Application Connector Registration

The Manage Application Connectors link on the Web Services page is used to register, test and enable or disable application connectors. Only SAP Concur Internal staff can access the Manage Application Connectors link.

To Access Application Connector Registration:
  1. On the home page, select Administration Web Services. The Web Services page appears.
  2. Click Manage Application Connectors. The Application Connector Registration page appears.

Registering an Application Connector

Once a development partner has configured a application connector, it must be registered with SAP Concur.

To Register an Application Connector:
  1. On the Application Connector Registration page, click New.
  2. In the System area, complete all of the required fields.

    Field Description
    Name Enter the name that should appear in the list of connectors.
    Description Enter the description of the function of the connector, such as what back-end system it might connect to.
    Host Name Enter the hostname for the connector. Example: https://{servername}
    User Name Enter the user name required to authenticate with the host. This must be the same as the user name specified in the configuration file for the application connector.
    Password Enter the password required to authenticate with the host. This must be the same as the password specified in the configuration file for the application connector.
  3. Click Test Connection. SAP Concur will attempt to connect to the test connection endpoint https://(host name)/system/v1.0/testconnection, using a GET method with the supplied credentials as HTTP Basic Authentication. If you have not configured the test connection endpoint, the test will fail.

    Note: A successful Test Connection request is required to set the connector to “Verified” before it can be used for any of the callout services.

  4. In the Services section, select an outbound message or callout that the connector will interact with.

  5. Click Configure. The Configure Service window appears.

  6. Enter the endpoint that the SAP Concur will connect to on the host. Example: /attendee/v1.0/find

  7. Select the Enabled check box if the endpoint is ready for use. Usually you will do this after you have implemented and tested the endpoint in your application connector.

  8. Click Save. The service is configured for your host.

  9. Repeat steps 4-8 for each service to configure.

  10. Click Save.

Modifying an Application Connector Registration

Once an application connector registration has been created, the fields can be modified. Services can be enabled or disabled from the Modify page.

To Modify an Application Connector:
  1. On the Application Connector Registration page, select the desired registration from the list.
  2. Click Modify.
  3. Edit the system fields as necessary.
  4. Click Test Connection to verify your changes.
  5. Edit the services configurations as necessary.
  6. Click Save to return to the Application Connector Registration page.

Deactivating an Application Connector Registration

Application connector registrations can't be removed, but can be deactivated. Connectors are deactivated by setting all the associated services to inactive.

To Deactivate an Application Connector:

  1. On the Application Connector Registration page, select the desired connector.
  2. Click Modify.
  3. Select the active Service.
  4. Click Configure.
  5. Clear the Active check box.
  6. Click OK.
  7. Click Save.

Delete notification requests

Delete an event notification.

URI

https://www.concursolutions.com/api/platform/notifications/v1.0/notification/

Delete Notification - Request

Request Parameters

notificationID: The unique identifier for the notification. Required.

Example:
https://www.concursolutions.com/api/platform/notifications/v1.0/notification/{notificationID}

URI Source: The URI is returned in the NotificationUrl element of the Response for the Get Notifications by Status function.

Headers

Authorization Header

Authorization header with OAuth token for valid SAP Concur user. Required.

The OAuth consumer must have one of the following user roles in SAP Concur: Company Administrator or Web Services Administrator for Professional, or Can Administer for Standard.

Accept Header

DELETE https://www.concursolutions.com/api/platform/notifications/v1.0/notification/nOB1KNTDSV0UqiYeTsy6su$praZSogRJB6 HTTP/1.1
Authorization: OAuth {access token}

XML Example Request

Delete Notification - Response

Content Types

Delete Notification - Schema

The response returns an HTTP Status Code as follows:

HTTP Code Description
200 Success Notification successfully deleted.
400 Bad Request The request is malformed. Check the API document and verify the request uses the correct format.
403 Forbidden The OAuth Consumer doesn't have a required role. Check the API documentation to learn the required roles.

Example of Successful Response

HTTPS 200 Success

Event Notification Callout

The Event Notification callout allows clients to choose to be notified through web services when certain actions take place in their SAP Concur company. If the client uses Concur Expense, the supported events are the Expense report entering the Post-Submit or Pre-Extract workflow steps. If the client uses Concur Travel Request, the supported events are the Travel Request entering the Post-Submit or Pre-Extract workflow steps. When the event happens, SAP Concur generates a notification and places it into the notification system queue. When the notification reaches the front of the queue, SAP Concur sends a request to the configured endpoint with event information.

This callout differs from the standard SAP Concur web services in the following ways:

Contents

Event Notifications - Process Flow

Process Flow for the Event Notification Callout

Event Notifications - Products and Editions

Example Use Case

An example use of this callout is:

  1. A SAP Concur user submits an expense report, triggering an Event Notification.
  2. The notification is placed in a queue and processed in a first come, first served order.
  3. When the notification gets to the front of the queue, it is sent to the endpoint specified by the developer.
  4. The application connector returns the HTTP 200 status code, and the notification is removed from the queue.
  5. The developer uses the Report information to make the Get Expense Report Details request.
  6. The developer uses the additional information to validate some expense report information.
  7. The developer then uses the Post Expense Report Exceptions function to approve the report.

This is one use case for the Event Notification callout, however it can be used for a wide variety of requirements.

Product Restrictions

SAP Concur products are highly configurable, and not all clients will have access to all features.

Partner developers must determine which configurations are required for their solution prior to the review process.

Existing clients can work with Concur Advantage Technical Services to create custom applications that work with their configuration.

Event Notification Process Overview

The configuration process has the following steps:

  1. Third-party developer, client or SAP Concur downloads, installs, configures, and customizes the application connector. The application connector may make requests to the inbound web services.

  2. The developer or the SAP Concur clients registers the application connector.
    Refer to Installation > Process for the detailed steps.

Once the configuration is complete, the callout uses the following process:

  1. The configured event occurs in SAP Concur.
  2. SAP Concur sends the request information to the specified endpoint for the application connector.

Event Notifications - Security

SAP Concur will make calls to the application connector's endpoint using SSL. During configuration, SAP Concur will connect to the application connector to validate that its hostname and access credentials are valid.

In the code SAP Concur provides for a sample application connector, credentials are stored in a web configuration file that varies by platform, such as web.xml or web.config. However, if you are hosting the connector, you can customize where and how the credentials are stored by customizing HTTPBasicAuth.java or Authentication.cs.

Expense or Travel Request will not be able to connect to the application connector until a certificate signed by a Certificate Authority (CA) is installed in the application connector. If you are hosting the application connector, you will need to install the signed certificate before SAP Concur can access the connector.

Event Notifications - Authentication

Authentication between SAP Concur and the application connector is performed using HTTP Basic Auth. By default, these credentials are stored in the appropriate web configuration file for your platform, such as web.xml or web.config. These credentials are entered in SAP Concur on the Register Application Connector page in Web Services under Administration.

Refer to the Callouts and Application Connectors page for more information.

Functions

Delete Notification

Get Notifications by Status

Post Event Notification Request 

Installation Process

The installation process includes installing the application connector, and registering it with SAP Concur.

  1. The third-party developer or client will create and install the application connector on their web site or a third party hosting site. The connector should be programmed to accept the requests from SAP Concur and provide the documented responses.
  2. The client registers the application connector with SAP Concur:

    1. Log in to SAP Concur as an administrative user.
    2. Select Administration > Web Services.
    3. Click Manage Application Connectors.
    4. Click New.
    5. Fill out the fields:
    Field Description
    Name Enter the name that should appear in the list of connectors.
    Description Enter the description of the function of the connector, such as what back-end system it might connect to.
    Host Name Enter the hostname for the connector. Example: https://{servername}
    User Name Enter the user name required to authenticate with the host. This must be the same as the user name specified in the configuration file for the application connector, using HTTP Basic Auth.
    Password Enter the password required to authenticate with the host. This must be the same as the password specified in the configuration file for the application connector, using HTTP Basic Auth.
    1. In the Services section, select Send Notification.
    2. Click Configure. The Configure Service window appears.
    3. Enter the endpoint that SAP Concur will connect to on your server. Example: /concur/v1.0/notify
    4. Select the Enabled check box if the endpoint is ready for use. Usually you will do this after you have implemented and tested the endpoint in your application connector.
    5. In the Workflows section, select the workflow step for each expense report or travel request workflow that requires notifications.
    6. Click OK.
    7. Click Test Connection. SAP Concur will attempt to access the configured endpoint with the provided user credentials.
    8. Click Save. The application connector is now registered with SAP Concur and enabled.

Responses and Errors

Refer to the HTTP Status Codes page for details of the common responses and errors.

Fetch Attendee Version 2 Callout

The Concur Fetch Attendee version 2.0 callout allows clients to import attendee information from their internal system to SAP Concur when a user is adding attendees to an entry. The SAP Concur service sends the attendee search fields to an application connector, created by the client, a third-party developer, or SAP Concur. The connector is hosted by the client or third-party developer, and has access to the attendee system of record. The connector uses the attendee information sent from SAP Concur to search for all matching attendee records in the client's system. Once the connector has the list of possible matches, it sends the attendee data to SAP Concur. The user sees the list of matches and can select the appropriate attendee for the entry.

This callout differs from the standard SAP Concur web services in the following ways:

Contents

Fetch Attendee - Process Flow

A process flow diagram showing flow between SAP Concur, an application connector, and client's data source

Fetch Attendee - Products and Editions

Fetch Attendee - Product Restrictions

Callout Details

Information on how to download, install, and configure the application connector is included in Callouts > Core Concepts.

Fetch Attendee Process Overview

The configuration process has the following steps:

  1. Client, third party developer, or SAP Concur downloads, installs, configures, and customizes the application connector.
  2. Optional for Professional / Premium Only: Client SAP Concur admin creates a new attendee type to use with the connector.
  3. Client registers the application connector, selecting the attendee types that will use the connector. Once the configuration is complete, the callout uses the following process:
    1. The user selects the appropriate attendee type in the Search Attendees window.
    2. The user enters information into an attendee field and clicks Search.
    3. SAP Concur sends the attendee search field information to the application connector. This request includes all attendee fields, with any blank values formatted as an empty string.
    4. The application connector queries the attendee system of record and returns a list of results to SAP Concur.
      NOTE: The results list is limited to 100 records.
    5. SAP Concur displays the results in the Search Results section of the Search Attendees window.
      NOTE: If the application connector does not respond or returns an error, the user is notified in a popup window within SAP Concur. SAP Concur will not resend the request unless the user manually initiates the search again.
    6. If the user adds the attendees to the entry, the attendee information is saved in SAP Concur.

Fetch Attendee - Security

SAP Concur will make calls to the application connector's endpoint using SSL. During configuration, SAP Concur will connect to the application connector to validate that its hostname and access credentials are valid.

SAP Concur will not be able to connect to the application connector until a certificate signed by a Certificate Authority (CA) is installed in the application connector. You will need to install the signed certificate before SAP Concur can access the connector.

Fetch Attendee - Authentication

Authentication between SAP Concur and the application connector is performed using HTTP Basic Auth. By default, these credentials are stored in the appropriate web configuration file for your platform, such as web.xml or web.config. These credentials are entered in SAP Concur on the Register Application Connector page in Web Services under Administration.

Refer to the Installation Process for more information.

Fetch Attendee - Functions

Version 3.0: Post Attendee Search Request

Fetch Attendee - Installation Process

The installation process includes installing the application connector, and registering it with SAP Concur.

First, the client or third-party developer will create and install the application connector on their web site or a third party hosting site. The connector should be programmed to accept the requests from SAP Concur and provide the documented responses.

During installation, the client or developer will select and configure an externally available endpoint on the host server for SAP Concur to send the attendee search request to.

The client then registers the application connector with SAP Concur:

  1. Log in to SAP Concur as an administrative user.
  2. Select Administration > Web Services.
  3. Click Manage Application Connectors.
  4. Click New.
  5. Fill out the fields according to the Application Connector Fields table shown below.
  6. In the Services section, select Fetch Attendee.
  7. Click Configure. The Configure Service window appears.
  8. Enter the endpoint that the SAP Concur will connect to on your server. Example: /attendee/v2.0/fetch. Note: The endpoint name should contain 'v2.0', otherwise the API defaults to v1.0 and returns a different set of fields.
  9. Select the Active check box if the endpoint is ready for use. Usually you will do this after you have implemented and tested the endpoint in your application connector.
  10. Select the attendee types that will use the application connector. These attendee types will be automatically configured to not allow users to create new attendees manually.
  11. Click OK.
  12. Click Test Connection. SAP Concur will attempt to access the configured endpoint with the provided user credentials.
  13. Click Save. The application connector is now registered with SAP Concur and enabled.

Application Connector Fields

Field Description
Name Enter the name that should appear in the list of connectors.
Description Enter the description of the function of the connector, such as what back-end system it might connect to.
Host Name Enter the hostname for the connector. Example: https://{servername}
User Name Enter the user name required to authenticate with the host. This must be the same as the user name specified in the configuration file for the application connector, using HTTP Basic Auth.
Password Enter the password required to authenticate with the host. This must be the same as the password specified in the configuration file for the application connector, using HTTP Basic Auth.1.0

SAP Concur Configuration

The SAP Concur administrator can select which attendee types use the connector when registering the application connector. These attendee types will be automatically configured to not allow users to create new attendees manually.

Professional/Premium Only: If desired, the administrator can create a new attendee type specifically for use with the connector.

Responses and Errors

Refer to the HTTP Status Codes for details of the common responses and errors.

Fetch List Callout

The Concur Fetch List callout allows clients to import list items from an internal system to Expense when a user is filling out list fields for an expense. The Expense service sends a request for list items to an application connector, created by the client, a third-party developer, or SAP Concur. The connector is hosted by the client or developer, and has access to the list item system of record. The connector uses the list information sent from Expense to search for all matching list items in the system of record. Once the connector has the list items, it sends the data to Expense. The user sees the list items and can select the appropriate item for the expense. When the user saves the expense, the list item is added to the list within Expense.

This callout differs from the inbound SAP Concur web services in the following ways:

Contents

Fetch List Callout - Process Flow

A process flow diagram showing flow between SAP Concur, an application connector, and client's data source

Fetch List Callout -Products and Editions

Fetch List Callout -Product Restrictions

SAP Concur products are highly configurable, and not all clients will have access to all features.

Partner developers must determine which configurations are required for their solution prior to the review process.

Existing clients can work with Concur Advantage Technical Services to create custom applications that work with their configuration.

Fetch List Callout -Process Overview

The configuration process has the following steps:

  1. Third-party developer, client or SAP Concur downloads, installs, configures, and customizes the application connector.
  2. SAP Concur registers the application connector.
  3. Expense Admin creates a new list in List Management.
  4. SAP Concur configures the list to search for external items.
  5. If using a connected list, Expense Admin creates a connected list definition in Forms and Fields.

Once the configuration is complete, the callout uses the following process:

  1. The user selects the external source list field while creating an expense entry.
  2. Expense sends the list field information and the item codes for the previously selected levels (for connected lists) to the application connector.
  3. The application connector queries the list system of record and returns the set of list items to Expense.
  4. Expense displays the list items in a drop down list.
  5. The user selects the desired list item and saves the expense.

Fetch List Callout - Security

SAP Concur will make calls to the application connector's endpoint using SSL. During configuration, SAP Concur will connect to the application connector to validate that its hostname and access credentials are valid.

In the code SAP Concur provides for a sample application connector, credentials are stored in a web configuration file that varies by platform, such as web.xml or web.config. However, if you are hosting the connector, you can customize where and how the credentials are stored by customizing HTTPBasicAuth.java or Authentication.cs.

Expense will not be able to connect to the application connector until a certificate signed by a Certificate Authority (CA) is installed in the application connector. You will need to install the signed certificate before SAP Concur can access the connector.

Fetch List Callout -Authentication

Authentication between SAP Concur and the application connector is performed using HTTP Basic Auth. By default, these credentials are stored in the appropriate web configuration file for your platform, such as web.xml or web.config. These credentials are entered in SAP Concur on the Register Application Connector page in Web Services under Administration.

Fetch List Callout -Functions

Concur Expense Configuration

Expense must have a list field configured to use an external source before this callout can be used. The client creates the list, SAP Concur configures it to use the external source, and the client creates the connected list definition if necessary.

Fetch List Callout - Responses and Errors

Refer to the HTTP Status Codes page for details of the common responses and errors.

Get notifications by status

Retrieves the list of event notifications that are in the supplied status.

Get notifications by status - Request

Request Parameters

status={status}
The desired status for the notification. Required. Currently supports failed.

Example:
https://www.concursolutions.com/api/platform/notifications/v1.0/notification?status={status}

Headers

Authorization Header

Authorization header with OAuth token for valid SAP Concur user. Required.

The OAuth consumer must have one of the following user roles in SAP Concur: Company Administrator or Web Services Administrator for Professional, or Can Administer for Standard.

Accept Header

Content-Type Header

application/xml

Get Notifications Status - XML Example Request

GET https://www.concursolutions.com/api/platform/notifications/v1.0/notification?status=FAILED HTTP/1.1
Authorization: OAuth {access token}
Accept: application/xml

Get notifications by status - Response

Supported Content Types

Get notifications by status - Schema

This request will return a NotificationsList parent element with a Notification child element for each failed notification. The Notification elements will have a Failure child element if the notification is failed.

Failure Elements

Element Description
Context Message that the callout can use to provide the developer some context for the callout.
EventDateTime When the event happened. Format: YYYY-MM-DD:HH:MM:SS
EventType The event that triggered the callout.
NotificationURL The URL the developer calls to delete a failed notification.
ObjectType The type of object that triggered the notification.
ObjectURI The URI for the object. The developer can use the appropriate GET function for the Object Type.

XML Example of Successful Response

HTTP/1.1 200 OK
Content-Length: 626
Content-Type: application/xml

<?xml version="1.0" encoding="utf-8"?>
<NotificationList xmlns="http://www.concursolutions.com/api/notification/2012/06" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
    <Notification>
        <Context i:nil="true" />
        <EventDateTime>2012-11-14T19:45:25</EventDateTime>
        <EventType>Report Entered Expense Report Workflow Step - REPORT SUBMITTED</EventType>
        <NotificationURI>https://www.concursolutions.com/api/platform/notifications/v1.0/notification/nOB1KNTDSWUcJPMV6dPDjNc$scu6EDbt9s</NotificationURI>
        <ObjectType>EXPRPT</ObjectType>
        <ObjectURI>https://www.concursolutions.com/api/expense/expensereport/v1.1/reportfulldetails/nxxKgLlnROzz$sHcpnRHQ$pALxamClaFfdC</ObjectURI>
    </Notification>
</NotificationList>

JSON Example of Successful Response

HTTP/1.1 200 OK
Content-Length: 388
Content-Type: application/json; charset=utf-8

[
  {
    "Context": null,
    "EventDateTime": "2012-11-14T19:45:25",
    "EventType": "Report Entered Expense Report Workflow Step - REPORT SUBMITTED",
    "NotificationURI": "https://www.concursolutions.com/api/platform/notifications/v1.0/notification/nOB1KNTDSWUcJPMV6dPDjNc$scu6EDbt9s",
    "ObjectType": "EXPRPT",
    "ObjectURI": "https://www.concursolutions.com/api/expense/expensereport/v1.1/reportfulldetails/nxxKgLlnROzz$sHcpnRHQ$pALxamClaFfdC"
  }
]

Launch an External URL Request

SAP Concur will send a request with the information in an encoded query string when the user clicks the button.

Launch An External URL - Request

URI

The Launch External URL callout launches the URI for the application connector, which can be in a custom location for each client. The standard location is:

https://{servername}/concur/form/v1.0/get

The URI is configured on the Register Application Connector page in Web Services under Administration.

The full URI for the request includes the following query string values:

https://{servername}/concur/form/v1.0/get?xcompanydomain={URL-encoded company domain}
    &xuserid={URL-encoded login ID of interactive user}
    &itemurl={URL-encoded url to item}
    &nonce={URL-encoded timestamp}
    &signature={URL-encoded signature hash}

Request Schema

Value Description
xcompanydomain The company domain.
xuserid The SAP Concur user ID of the logged-in user. This may be an expense delegate instead of the report owner. To get the report owner ID, use the itemurl to get the details of the expense entry, then use those details to get the associated report details, including the report owner ID.
itemurl The URL-encoded URI to access the item the field appears on. An example would be the expense entry URI used by the Expense Report web service.
nonce The URL-encoded GUID used to generate the signature.
signature The URL-encoded signature hash.

Launch An External URL - Authentication

To authenticate the request, the developer of the page in the application connector will need to generate an auth signature and compare it with the one passed in the query string.

When the request is received by the connector:

  1. Obtain the username and password for the application connector. How you do this will be specific to your implementation.
  2. Parse and URL decode the following from the query string:
    1. xcompanydomain
    2. xuserid (used for subsequent web service call)
    3. itemurl
    4. nonce
    5. signature (used to authenticate and verify the request)
  3. Base64-decode the provided signature.
  4. Calculate your own base signature string by appending the values as such:
    {xcompanydomain} + {xuserid} + {itemurl} + {connector username} + {connector password} + {nonce}
  5. Use HMacSHA1 to generate a signature hash using the base signature string. To generate the key, concatenate the lower-case value for {connector username} and the exact {connector password}. For example, if the connector user name is JohnDoe, and the password is password, the key would be johndoepassword.
  6. Compare the generated signature hash with the signature hash provided in the request query string. If the signature hashes match then you know the credentials are valid and the request has not been tampered with.

NOTES:

Launch An External URL - XML Example Request

GET https://{URL to your custom connector and endpoint}
?xcompanydomain={URL-encoded company domain}
    &xuserid={URL-encoded login ID of interactive user}
    &itemurl={URL-encoded url to item}
    &nonce={URL-encoded timestamp}
    &signature={URL-encoded signature hash}

Launch An External URL - Response

Content Body

The application connector does not directly respond to the Launch External URL request. The application connector completes any updates to SAP Concur using the Inbound Web Services. The Launch External URL functionality monitors the external window, and when the window is closed, it redraws the form the user launched from to display any updated values.

Launch External URL Callout

The Launch External URL callout gives clients and developers a platform to extend the functionality of SAP Concur providing a means to deliver custom user interactions, or access functionality found in an external system. The client can arrange to add an Expense Entry form field that is configured to use the Launch External URL callout to a Concur Expense Entry form. Concur Expense will display this field with an attached button that launches a separate window when clicked. The window is controlled by an application connector, created by a third-party developer, the client, or SAP Concur. The application connector is a web server that presents information in the window.

The application connector can access SAP Concur data through the web services, or can access data in an external system. Once the user has completed their actions in the window (such as performing a search or completing a wizard), he/she clicks a button such as "Done" that indicates the user has concluded their work in the window. The application connector then closes the window. 

The application connector can use web services to send information to SAP Concur to update field values on the expense entry form or other form types. The application connector may send the updates before or after the user closes the window. When the user returns to SAP Concur, the page refreshes and he/she sees the updated values.

This callout differs from the standard SAP Concur web services in the following ways:

Contents

Launch External URL Callout - Process Flow

Process Flow for Launch External Service

Launch External URL Callout - Products and Editions

Launch External URL Callout - Product Restrictions

This callout is not supported in the SAP Concur mobile application.

SAP Concur products are highly configurable, and not all clients will have access to all features.

Only the Employee role can interact with the Launch External URL configured field. Other roles such as the Approver and Processor are not able to trigger the pop-up window.

Partner developers must determine which configurations are required for their solution prior to the review process.

Existing clients can work with SAP Concur Integration Services to create custom applications that work with their configuration.

Launch External URL Callout - Callout Details

Information on how to download, install, and configure the application connector is included in Callouts and Application Connectors.

Launch External URL Callout - Process Overview

The configuration process has the following steps:

  1. Third-party developer, client or SAP Concur downloads, installs, configures, and customizes the application connector. The application connector may make requests to the inbound web services.
  2. SAP Concur registers the application connector. SAP Concur must add the IP address and domain of the application connector to an include list. Be ready to supply the test and production domain information.
  3. Expense Admin creates a new form field with the Launch External URL control type and adds the field to the expense entry form(s).

Once the configuration is complete, the callout uses the following process:

  1. The user clicks the button next to the read-only form field.
  2. Expense launches a new window and sends the Expense Entry Details URI, Company Domain, and X-User ID in an encoded query string to the application connector.
  3. The application connector parses the query string to extract the sent data.
  4. The application connector uses a SAP Concur web service to gather information. This may be expense entry information, user information, or other information.
  5. The application connector presents a web page in the new window for the user to interact with. This can be a page from a commercial application, or a custom web application.
  6. The user completes the external system process. This could be a search, a wizard, or another process.
  7. The application connector sends any field update information to SAP Concur using the SAP Concur web services.
  8. The user or the application connector closes the window and returns to SAP Concur.
  9. SAP Concur reloads the page the user came from in order to display any updated field values.

Launch External URL Callout - Security

SAP Concur will make calls to the application connector's endpoint using SSL. During configuration, SAP Concur will connect to the application connector to validate that its hostname and access credentials are valid.

In the code SAP Concur provides for a sample application connector, credentials are stored in a web configuration file that varies by platform, such as web.xml or web.config. However, if you are hosting the connector, you can customize where and how the credentials are stored by customizing HTTPBasicAuth.java or Authentication.cs.

Expense will not be able to connect to the application connector until a certificate signed by a Certificate Authority (CA) is installed in the application connector. You will need to install the signed certificate before SAP Concur can access the connector.

Launch External URL Callout - Authentication

SAP Concur sends requests to the application connector using anonymous authorization (no username and password are provided) over HTTPS.

The application connector can validate the authenticity of the query by generating a signature hash from the provided variables and comparing it with the passed in values, including the signature hash that SAP Concur supplies. Two of the required variables for the signature hash are username and password, which are entered in SAP Concur on the Register Application Connector page in Web Services under Administration. The application connector must use the same username and password pair to generate it's validation signature hash.

Launch External URL Callout - Functions

Launch External URL Request

Launch External URL Callout - Concur Expense Configuration

An Expense text form field must be configured as the Launch URL control type and the form field must be added to the desired form before this callout can be used. The Launch URL control type will not appear in the list until a partner application using the Launch External URL API has been registered and enabled for the company. The administrator must select either a single-line or a multi-line control type, depending on the data that will be placed in the field.

Notes:

Launch External URL Callout - Responses and Errors

Refer to the HTTP Codes page for details of the common responses and errors.  

Post an event notification request

Post an event notification - Request

Supported Accept Types

URI

The Event Notification callout sends the notification to a URI for the application connector, which can be in a custom location for each client. The standard location is:

https://{servername}/concur/v1.0/notify

The URI is configured on the Register Application Connector page in** Web Services** under Administration.

Request Headers - Required

Authorization header with Basic authorization for endpoint. Refer to Authentication for more information.

Request Headers - Optional

None

Post an event notification request - Request Schema

The request will include a Notification parent element, with the following child elements:

Element Description
EventType The event that triggered the callout. Format: Report Entered Expense Report Workflow Step - .
ObjectType The type of object that triggered the notification. Currently supports Expense Report and Travel Request. Format: EXPRPT, TRAVELREQ
ObjectURI The URI for the object. The developer can use the appropriate GET endpoint for the Object Type.
EventDateTime When the event happened. Format: YYYY-MM-DD
Context Message that the callout can use to provide the developer some context for the callout.

Post an event notification request - XML Example Request

POST /concur/v1.0/notify HTTPS/1.1
Host: www.example.com
Authorization: Basic Y29uY3VyOmNvbmN1cg==
...

<?xml version="1.0" encoding="UTF-8" ?>
<Notification>
    <EventType>Report Entered Expense Report Workflow Step - SUBMIT</EventType>
    <ObjectType>EXPRPT</ObjectType>
    <ObjectURI>https://www.concursolutions.com/api/expense/expensereport/v1.1/reportfulldetails/3%Rek29$wsIY12Di3LS9$gjei%KL23</ObjectURI>
    <EventDateTime>2012-05-01</EventDateTime>
    <Context/>
</Notification>

Post an event notification request - Response

Supported Content Types

Content Body

The application connector responds with an HTTP 200 code when it successfully receives the notification.

Post an event notification request - Example of Successful Response

HTTPS 200 Success

Post an attendee search request

Post an attendee search request - Request

URI

The Fetch Attendee version 2.0 callout sends the attendee information to a URI for the application connector, which can be in a custom location for each client. The default is:

https://{servername}/concur/attendee/v2.0/fetch

For backward compatibility, Fetch Attendee version 1.0 is used instead of version 2.0 when the URI uses v1.0 instead of v2.0. The URI is configured on the Application Connector Registration page under Web Services>Administration>Manage Applications.

The application connector responds to the Fetch Attendee request by returning all attendees that match the search criteria. The result is limited to the maximum number of records specified in the request. If more than the maximum number of records are sent, SAP Concur Expense displays a message in the Attendee Search window asking the user to refine their search. The authorization functionality in version 2.0 is the same as version 1.0

Headers

Authorization Header

Required. Authorization header with Basic authorization for endpoint. Refer to Authentication for more information.

Post an attendee search request - Request Schema

The request body contains an AttendeeSearchRequest parent element with an Attendee child element. The Attendee elements contain the values entered on the search form.

Attendee Elements

Element Description
AttendeeTypeCode Code for the attendee type assigned to this attendee. Maximum length is 8 characters.
Company Attendee's company. Also used for Institution Name for Healthcare Provider attendees. Maximum length is 150 characters. Required in the response.
Custom1 through Custom20 Custom fields which vary for a given configuration. Maximum length is 100 characters. Required in the response.

For clients who purchased the HCP Connector, Custom7, Custom8, and Custom9 are mapped to the HCP Attendee Form as follows:
Custom7: License number
Custom8: State of license
Custom9: Healthcare specialty description
Custom21 through Custom25 Custom fields which vary for a given configuration. Maximum length is 100 characters. Required in the response.
For clients who purchased the HCP Connector, Custom15, Custom21, Custom22, and Custom23 are mapped to the HCP Attendee Form as follows:
Custom15: Healthcare practice address
Custom21: Attendee taxonomy
Custom22: Attendee tax ID
Custom23: Covered recipient ID
ExternalID Attendee's unique identifier outside of SAP Concur. Maximum length is 48 characters.
FirstName Attendee's first name. Maximum length is 50 characters.
LastName Attendee's last name. Maximum length is 132 characters.
MaximumNumberRecords Maximum number of records that will be returned to the user for the given search criteria.
MiddleInitial Attendee's middle initial. Maximum length is 1 character.
OwnerLoginID SAP Concur Login ID for the report owner (not the logged in user). The developer can use the User Resource: GET endpoint to obtain user profile details that identify the user and use this information to search for attendees in the system of record for that user.
Suffix Attendee's name suffix. Maximum length is 32 characters.
Title Attendee's title. Maximum length is 32 characters.

Post an attendee search request - XML Example Request

POST /concur/attendee/v1.0/fetch HTTPS/1.1
Host: example.com
Authorization: Basic ...
Content-Type: application/xml; charset=utf-8
Content-Length: {length of content body}

<AttendeeSearchRequest>
    <Attendee>
        <AttendeeTypeCode>BUSGUEST</AttendeeTypeCode>
        <FirstName>Chris</FirstName>
        <MiddleInitial />
        <LastName>Miller</LastName>
        <Suffix />
        <Title>CFO</Title>
        <Company>Len Dev</Company>
        <ExternalID />
        <OwnerLoginID>cm@example.com</OwnerLoginID>
        <MaximumNumberRecords>500</MaximumNumberRecords>
        <Custom1 />
        <Custom2 />
        <Custom3 />
        <Custom4 />
        <Custom5 />
        <Custom6 />
        <Custom7 />
        <Custom8>North America</Custom8>
        <Custom9 />
        <Custom10 />
        <Custom11 />
        <Custom12 />
        <Custom13 />
        <Custom14 />
        <Custom15 />
        <Custom16 />
        <Custom17 />
        <Custom18 />
        <Custom19 />
        <Custom20 />
        <Custom21 />
        <Custom22 />
        <Custom23 />
        <Custom24 />
        <Custom25 />
    </Attendee>
</AttendeeSearchRequest>

Post an attendee search request - Response

Supported Content Types

application/xml

Response Schema

The response will include an AttendeeSearchResponse parent element, with an Attendee child element for each search result.

If no attendees match the search criteria, the response returns an empty AttendeeSearchResponse.

Attendee Elements

The Attendee child element must contain all of the elements described below. The FirstName, LastName, and ExternalID elements must have values. All other elements must be returned in the response, however they can be empty if no data is available.

Element Description
AttendeeTypeCode The attendee type code for the attendee type assigned to this attendee. Maximum length: 8
Company The attendee's company. Required in the response. Also used for Institution Name for Healthcare Provider attendees. Maximum length: 150
Custom1 through Custom25 Varies depending on configuration. Required in the response. Maximum length of Custom1 through Custom20: 100 characters. Maximum length of Custom21 through Custom25: 48 characters. For information about Custom fields that are used by healthcare providers, see the Custom fields for healthcare provider attendees table below.
ExternalID The attendee's unique identifier outside of SAP Concur. Maximum length: 32
FirstName The attendee's first name. Maximum length: 50
LastName The attendee's last name. Maximum length: 132
MiddleInitial The middle initial of the attendee. Maximum length: 1.
Suffix The suffix of the attendee. Maximum length: 32.
Title The attendee's title. Maximum length: 32

Custom Fields for Healthcare Provider Attendees

Field Description
Custom7 License Number
Custom8 State of License
Custom9 Specialty Description
Custom13 Recipient Type/Professional Designation
Custom14 NPI Number
Custom15 Primary Practice Address Line 1
Custom16 Primary Practice Address Line 2
Custom17 Primary Practice Address Line 3
Custom18 Primary Practice City
Custom19 Primary Practice State
Custom20 Primary Practice Zip Code
Custom21 Taxonomy. Max 48 characters.
Custom22 Tax ID. Max 48 characters.
Custom23 Covered Recipient ID. Max 48 characters.

NOTES:

Post Fetch Attendee - XML Example of Successful Response

HTTPS/1.1 200 OK
Content-Type: application/xml
Content-Length: {length of content body}

<AttendeeSearchResponse>
    <Attendee>
        <ExternalID>1234567890</ExternalID>
        <FirstName>Chris</FirstName>
        <MiddleInitial>T</MiddleInitial>
        <LastName>Miller</LastName>
        <Suffix/>
        <Company>Len Dev</Company>
        <AttendeeTypeCode>BUSGUEST</AttendeeTypeCode>
        <Title>CFO</Title>
        <Custom1/>
        <Custom2/>
        <Custom3/>
        <Custom4/>
        <Custom5/>
        <Custom6/>
        <Custom7>RD</Custom7>
        <Custom8>North America</Custom8>
        <Custom9>Internal Medicine</Custom9>
        <Custom10/>
        <Custom11/>
        <Custom12/>
        <Custom13/>
        <Custom14/>
        <Custom15>100 Main Street, Bellevue, WA 98040</Custom15>
        <Custom16/>
        <Custom17/>
        <Custom18/>
        <Custom19/>
        <Custom20/>
        <Custom21>Tax ID 1234</Custom21>
        <Custom22/>
        <Custom23>Patient ID 576</Custom23>
        <Custom24/>
        <Custom25/>
    </Attendee>
</AttendeeSearchResponse>

The following example shows the expected response when no attendees match the search criteria.

HTTPS/1.1 200 OK
Content-Type: application/xml
Content-Length: {length of content body}

<?xml version="1.0" encoding="utf-8"?>
<AttendeeSearchResponse/>

Post a list search request

Post A List Search - Request

Supported Accept Types

application/xml

URI

The Fetch List callout sends the attendee information to a URI for the application connector, which can be in a custom location for each client. The standard location is:

https://{servername}/concur/list/v1.2/fetch

The URI is configured on the Register Application Connector page in Web Services under Administration.

Request Headers - Required

Authorization header with Basic authorization for endpoint. Refer to Authentication for more information.

Request Headers - Optional

None

Post A List Search - Request Schema

The request will contain a fetch-list-request parent element, containing the following child elements.

Element Description
long-code The long code is a concatenated string containing the parent list item keys separated by a hyphen (-).
short-code The short code is the key of the parent list item.
query It is possible that the asterisk wildcard will be passed from Expense to the application connector.
  • Asterisk only (*) - Return all items in the list represented by the long code.
  • Text followed by asterisk (West*) - Return all items beginning with the text.
  • Asterisk followed by text - Return all items ending with the text.
search-by Indicates which list item attribute should be searched. Supported values: TEXT, CODE.
NOTE: The application connector must support both attributes in order to properly handle wildcard searches.
lang-code The two character code for the language of the user.
num-to-return Expense will specify the number of items to return. The application connector must use this value to ensure that it does not return more results than requested. There is a system limit of 1000 items.
protected-list-key Internal connector information, not used by customers.
list-name Internal connector information, not used by customers.
connector-version Internal connector information, not used by customers.
config-options Internal connector information, not used by customers.
code-by-level Indicates the code at each level in the case of a multi-level list.

XML Example Request for Single Level List

The example uses the Fetch List web service to search a single level list for all projects beginning with Alph, and is configured to connect to an application connector located at www.example.com.

POST /concur/list/v1.2/fetch HTTPS/1.1
Host: example.com
Authorization: Basic ...
Content-Type: application/xml; charset=utf-8
Content-Length: {length of content body}

<?xml version="1.0" ?>
<fetch-list-request>
    <long-code></long-code>
    <short-code></short-code>
    <query>Alph*</query>
    <search-by>TEXT</search-by>
    <lang-code>EN</lang-code>
    <num-to-return>500</num-to-return>
    <protected-list-key />
    <list-name />
    <connector-version />
    <config-options />
</fetch-list-request>

XML Example Request for Multi-Level List

The example uses the Fetch List web service to search a connected list for all cities under US-W-CA (United States, Western Region, California) beginning with San, and is configured to connect to an application connector located at www.example.com.

POST /concur/list/v1.2/fetch HTTPS/1.1
Host: example.com
Authorization: Basic ...
Content-Type: application/xml; charset=utf-8
Content-Length: {length of content body}

<?xml version="1.0" ?>
<fetch-list-request>
    <long-code>US-W-CA</long-code>
    <short-code>CA</short-code>
    <query>San*</query>
    <search-by>TEXT</search-by>
    <lang-code>EN</lang-code>
    <num-to-return>500</num-to-return>
    <protected-list-key />
    <list-name />
    <connector-version />
    <config-options />
    <code-by-level>
        <level1>US</level1>
        <level2>W</level2>
        <level3>CA</level3>      
    </code-by-level>
 </fetch-list-request>

Post a list search - Response

Supported Content Types

application/xml

Post a list search - Response Schema

The application connector responds to the Fetch list web service request by returning all list items that match the search criteria.

The response will include a fetch-list-response parent element, with an item child element for each search result. If there are no search results, the fetch-list-response element is empty. The item child element contains the following child elements:

Element Description
code Required The long code for the list item, consisting of the long code from the request combined with the short code from the response, separated by a hyphen (-).
short-code Required The short code for the list item.
text Required The list item text.
match-value Required The value that matched the search term.

Post a list search request - XML Example of Response with Results

HTTPS/1.1 200 OK
Content-Type: application/xml
Content-Length: {length of content body}

<fetch-list-response>
    <item>
        <code>US-W-CA-SF</code>
        <short-code>SF</short-code>
        <text>San Francisco</text>
        <match-value>San Francisco</match-value>
    </item>
    <item>
        <code>US-W-CA-SD</code>
        <short-code>SD</short-code>
        <text>San Diego</text>
        <match-value>San Diego</match-value>
    </item>
    <item>
        <code>US-W-CA-SJ</code>
        <short-code>SJ</short-code>
        <text>San Jose</text>
        <match-value>San Jose</match-value>
    </item>
</fetch-list-response>

Post a list search - XML Example of Response with No Results

HTTPS/1.1 200 OK
Content-Type: application/xml

<fetch-list-response>
</fetch-list-response>

Travel Request Validation

Requests in SAP Concur can be validated in an external system by using a combination of SAP Concur's callouts and web services.

This guide provides a step by step overview of how to set up and use the external validation functionality for Requests. This guide does not provide instruction on the process of programming the application connector, but provides an overview of the required functionality.

Step 1 - Create an Application Connector

The application connector is a custom web application that is installed on your company's web server. This application needs to be accessible from outside your company's network, so that SAP Concur can send information to it, and it needs to have access to the system that you are using for validation. The application connector must be configured to accept the event notification requests from SAP Concur. In later steps, you will expand the functionality of the application connector to perform additional tasks. The required connector configuration for this step is:

Once you have the basic application connector functionality set up, you're ready to move to the next step.

Step 2 - Configure Event Notification and Request in SAP Concur

In this step, you will enable the Event Notification functionality in your SAP Concur company in order to receive information about submitted Requests. Then, you will enable the Request API in order to request Request details from SAP Concur.

Before you begin

Procedure: Create the Event Notification Application Connector

  1. Log in to SAP Concur as an administrative user.
  2. Select Administration > Web Services.
  3. Click Manage Application Connectors.
  4. Click New.
  5. Fill out the fields:
Field Description
Name Enter the name that should appear in the list of connectors.
Description Enter the description of the function of the connector, such as what back-end system it connects to.
Host Name Enter the hostname for the connector. Example: https://{servername}
User Name Enter the user name required to authenticate with the host. This must be the same as the user name specified in the configuration file for the application connector, using HTTP Basic Auth.
Password Enter the password required to authenticate with the host. This must be the same as the password specified in the configuration file for the application connector, using HTTP Basic Auth.
  1. In the Services section, select External Report Validation.
  2. Click Configure. The Configure Service window appears.
  3. Enter the endpoint that the SAP Concur will connect to on your server. Example: /concur/v1.0/notify
  4. Select the Enabled check box.
  5. In the Workflows section, select the Submit check box for each Request workflow that requires notifications.
  6. Click OK.
  7. Click Test Connection. SAP Concur will attempt to access the configured endpoint with the provided user credentials.
  8. Click Save. The application connector is now registered with SAP Concur and enabled.

Procedure: Create the Request Partner Application

  1. On the Web Services page, click Register Partner Application. The Application Registration page appears.
  2. Click New. The New Partner Application page appears.
  3. Complete all of the required fields:
Field Description
Name Enter the name that should appear in the list of applications.
Description Enter the description of the function of the application.
Visibility This field is only editable by SAP Concur Internal users.
Active Select Active.
APIs Used Select the Request API.
  1. The Application Authorization section displays your company domain and automatically creates a Key and Secret to use with this application.
    NOTE: The key and secret allow access to any company that enables this application. You MUST keep this information secret (as specified in the SAP Concur Legal Agreement) to maintain security.
  2. Record the key and secret to use later.
  3. Click OK. The application will automatically be enabled for your company.

You should now begin receiving notifications from SAP Concur when your users submit Requests. In the next step, you'll use the notification data that SAP Concur sends to get the Request information.

Step 3 - Gather the Request Details

In this step, you will expand the application connector functionality to use the data sent by SAP Concur in the event notification to get details about the Request. You'll use the Request details to validate the Request in a later step. The application connector must be updated to perform the following steps, using the SAP Concur web services:

Get OAuth Access Token

All requests to SAP Concur web services must be authenticated using OAuth 2.0.

After receiving an event notification, the application connector should send an HTTP GET request to the Get Access Token using Native Flow function. This function requires the login credentials of an administrative SAP Concur user and the Consumer Key that was generated when you created the partner application in the previous step. Refer to the Get Access Token using Native Flow documentation for the format of the request. SAP Concur will respond to the request with the access token required for the next web service request.

Get Request Details

After you receive the OAuth access token, you are ready to request the Request data. The event notification information that SAP Concur sends includes an element named ObjectURI. The connector can send a GET request to the URI specified in this element, supplying the OAuth access token in the request header in the following format:

GET api/travelrequest/v1.0/requests/nxxKgLlnROz3zHJBCRksaas23dsfs HTTPS/1.1
Host: www.concursolutions.com
Authorization: OAuth {access token}
...

Step 4 - Validate the Request Information

In this step, the connector will perform the required validation on the Request information. This step will vary by client. The application connector must be able to access the system(s) used in the validation.

The Request data is validated by the application connector. The validation can produce one of the following results:

In the next step, the application connector will update the Request with the validation results.

Step 5 - Update the Request Workflow

Once the Request has been validated, the application connector is ready to update its workflow. If the Request passed validation, it should be approved, and will then travel forward in its workflow. If the Request did not pass validation, it should be sent back to the employee, which moves it to the beginning of the workflow.

The full Request details include an element named WorkflowStepURL. The application connector posts the workflow action (Approve or Send Back to Employee) to this url, using the same OAuth access token in the header.

SAP Concur responds with a success or failure status, and provides additional information for failures.

The application connector has now completed the process of validating a Request, from the initial notification that a Request was submitted, to the request updating the Request workflow in SAP Concur with the validation results.

Common

Connection Requests v3.2

The Connection Requests resource is used to integrate TripLink partner applications with Concur. It can be used to create, update, and manage connections between a user's Concur account and a select travel loyalty program. With Connection Requests a TripLink partner application can retrieve new connection requests in order to match users who want to connect to the supplier with the user's account in the supplier system. After the request is retrieved, the supplier is expected to provide a status if the connection was successful or failed. When retrieving new connections, the results can be filtered by status, page offset, and a limit for the number of records to return.

In version 3.2, connection requests can also associate users to either loyalty programs, Concur verified e-mail addresses, or both of these factors. Concur verified emails are email addresses where a user has taken additional steps to confirm an email belongs to them by entering a verification code within the Concur UI after receiving this in their email. Verified emails have uniqueness across all user accounts in the Concur system.

The use of loyalty numbers and/or verified emails to identify users is based on the business agreement between Concur and the TripLink supplier and will be discussed during the TripLink integration kick-off process. Email or loyalty number will not be returned in the connection request if the supplier is not using these factors in their process to match a user in their system to a Concur user.

Concur's recommendation for suppliers is to match users requesting to connect utilizing last name and loyalty number only. Or in the case of suppliers without loyalty numbers to use verified email and the last name of the user only. The first name and middle name fields have proved to generate a high degree of failures when utilized due to issues like nicknames within the supplier systems.

GET /api/v3.2/common/connectionrequests/
GET /api/v3.0/common/connectionrequests/  (deprecated)
GET /api/v3.1/common/connectionrequests/  (deprecated)

Parameters

Name Type Format Description
offset query string The starting point of the next set of results, after the limit specified in the limit field has been reached. The default is the beginning of the page.
limit query Int32 The number of records to return. The default is 5 and the maximum is 10.
status query string The status code representing the state of the connection request. The possible values are Pending, Processing, Connected, Failed, and Retry.

Retrieve a connection request by ID

GET /api/v3.2/common/connectionrequests/{id}

GET /api/v3.0/common/connectionrequests/{id} (deprecated) GET /api/v3.1/common/connectionrequests/{id} (deprecated)

Parameters

Name Type Format Description
id path string Required The connection request ID.

Create a connection request on behalf of a specific user

POST /api/v3.2/common/connectionrequests/

POST /api/v3.0/common/connectionrequests/ (deprecated) POST /api/v3.1/common/connectionrequests/ (deprecated)

Parameters

Name Type Format Description
user query string Required The login ID of the user for whom to create the connection request. The user must have the Web Services Admin role to use this parameter.

Update a connection request

PUT /api/v3.2/common/connectionrequests/{id}

PUT /api/v3.0/common/connectionrequests/{id} (deprecated) PUT /api/v3.1/common/connectionrequests/{id} (deprecated)

Parameters

Name Type Format Description
id path string Required The connection request ID.
content body - Required The connection request object to update.

Schema 3.2

Connection Requests

Name Type Format Description
Items array Connection Request The result collection.
NextPage string The URI of the next page of results, if any.

Connection Request

Name Type Format Description
firstName string - The user's first name.
ID string - The unique identifier of the resource.
lastModified string - The date and time when the connection request was last modified. Format: UTC
lastName string - The user's last name.
loyaltyNumber string - The user's travel loyalty number.
middleName string - The user's middle name.
requestToken string - The request token.
status string - The status code representing the state of the connection request.
URI string - The URI to the resource.
userId string - The unique identifier of the user.
emailAddresses UserEmailAddresses User Email Addresses Email addresses associated with the user.

User Email Addresses

Name Type Format Description
email1 string - The user's verified email address.
email2 string - The user's verified email address.
email3 string - The user's verified email address.
email4 string - The user's verified email address.
email5 string - The user's verified email address.

Schema 3.0 (Deprecated)

Connection Requests

Name Type Format Description
Items array Connection Request The result collection.
NextPage string The URI of the next page of results, if any.

Connection Request

Name Type Format Description
FirstName string - The user's first name.
ID string - The unique identifier of the resource.
LastModified string - The date and time when the connection request was last modified. Format: UTC
LastName string - The user's last name.
LoyaltyNumber string - The user's travel loyalty number.
MiddleName string - The user's middle name.
RequestToken string - The request token.
Status string - The status code representing the state of the connection request.
URI string - The URI to the resource.

Schema 3.1 (Deprecated)

Connection Requests

Name Type Format Description
Items array Connection Request The result collection.
NextPage string The URI of the next page of results, if any.

Connection Request

Name Type Format Description
FirstName string - The user's first name.
ID string - The unique identifier of the resource.
LastModified string - The date and time when the connection request was last modified. Format: UTC
LastName string - The user's last name.
LoyaltyNumber string - The user's travel loyalty number.
MiddleName string - The user's middle name.
RequestToken string - The request token.
Status string - The status code representing the state of the connection request.
URI string - The URI to the resource.
EmailAddresses UserEmailAddresses User Email Addresses Email addresses associated with the user.

User Email Addresses

Name Type Format Description
Email1 string - The user's verified email address.
Email2 string - The user's verified email address.
Email3 string - The user's verified email address.
Email4 string - The user's verified email address.
Email5 string - The user's verified email address.

Extracts v1

Capabilities

The Extract web service allows for the development of a customized process that can be used to request and extract available data objects such as “Approved” Expense Reports, Invoices, and Payment Requests.

Through a series of web service calls an Application Connector can GET the Extract Definition List, then use that list to perform a POST the Extract Job of their choosing. This POST will initiate the extract process. While the job runs another process can periodically GET the Extract Job Status and once “Complete” the Connector can then perform a GET to obtain the Extract Job File data.

The series of calls that your connector will make will remain the same for each implementation of the Extract Web Service.

Additionally, it provides:

Note: A client may elect to include additional functionality that could result in complex journal entries. For example, they may allow cash advances or utilize a company-paid corporate card program where personal amounts result in an employee owing the employer. These configuration choices require more care when pulling the extract file from SAP Concur. Work with their functional experts on their specific use case, then watch the relevant videos in the SAE Detailed Discussions section at the bottom of the page for detailed information on which fields to include.

Resource URI

https://{InstanceURL}/api/expense/extract/v1.0
https://{InstanceURL}/api/expense/extract/v1.0/{DefinitionID}/job
https://{InstanceURL}/api/expense/extract/v1.0/{DefinitionID}/job/status
https://{InstanceURL}/api/expense/extract/v1.0/{DefinitionID}/job/{JobID}/file

Version

1.0

Base URI

/api/expense/extract/v1.0/

Authorization

The Authorization header with OAuth token for a valid SAP Concur user must be included with all API calls. The OAuth consumer must have one of the following user roles in SAP Concur: Company Administrator or Web Services Administrator for Professional, or Can Administer for Standard. These roles allow the user to manage data for the entire company.

Get an Array of Extract Definitions

Request

Headers

Parameters

None

Payload

Name Type Format Description
name type JSON Required Description.

Response

Status Codes

Headers

Payload

Definitions

Example

Request

GET https://www.concursolutions.com/api/expense/extract/v1.0/
Authorization: OAuth {token}

Response

HTTP/1.1 200 OK
Content-Type: application/xml
<definitions xmlns="http://www.concursolutions.com/api/expense/extract/2010/02">
  <definition>
    <id>https://www.concursolutions.com/api/expense/extract/v1.0/nYoPK$pZmcowMRUqcl5bnDAwwsMydyt$xd</id>
    <job-link>https://www.concursolutions.com/api/expense/extract/v1.0/nYoPK$pZmcowMRUqcl5bnDAwwsMydyt$xd/job</job-link>
    <name>Standard Accounting Extract</name>
  </definition>
  <definition>
    <id>https://www.concursolutions.com/api/expense/extract/v1.0/Umj$swS19lpd7Sk$phUYl67wE1ss4Q$shu</id>
    <job-link>https://www.concursolutions.com/api/expense/extract/v1.0/Umj$swS19lpd7Sk$phUYl67wE1ss4Q$shu</job-link>
    <name>European Extract</name>
  </definition>
  <definition>
    <id>https://www.concursolutions.com/api/expense/extract/v1.0/8LjhN23Hs33$piUUfy4ytTqa$sqqacYeP1</id>
    <job-link>https://www.concursolutions.com/api/expense/extract/v1.0/8LjhN23Hs33$piUUfy4ytTqa$sqqacYeP1</job-link>
    <name>Asian Extract</name>
  </definition>
</definitions>

Get a single extract definition

Retrieves the details of the specified extract definition.

Request

Headers

Parameters

Name Type Format Description
DefinitionID string - Required The identifier for the desired extract definition.
URI Template
https://www.concursolutions.com/api/expense/extract/v1.0/{DefinitionID}

Payload

Name Type Format Description
name type JSON Required Description.

Response

Status Codes

Headers

Payload

Definition

Example

GET https://www.concursolutions.com/api/expense/extract/v1.0/n59FpBJ8hN3qVWTFIrtxkOT5pef6DmIj3
Authorization: OAuth {token}

Request

HTTP/1.1 200 OK
Content-Type: application/xml

Response

<definition xmlns="http://www.concursolutions.com/api/expense/extract/2010/02" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
    <id>https://www.concursolutions.com/api/expense/extract/v1.0/n59FpBJ8hN3qVWTFIrtxkOT5$pef6DmIj3</id>
    <name>AMEX Remittance - US</name>
    <job-link>https://www.concursolutions.com/api/expense/extract/v1.0/n59FpBJ8hN3qVWTFIrtxkOT5$pef6DmIj3/job</job-link>
</definition>

Get an extract file or files

The extracted data for the specified extract job.

The response is the extracted data in text/csv format if there was a single file produced or as application/zip if the extract definition is configured to produce more than one file.

Request

Headers

Parameters

Name Type Format Description
DefinitionID string - Required The definition identifier.
JobID string - Required The identifier for the job.
URI Template
https://www.concursolutions.com/api/expense/extract/v1.0/{DefinitionID}/job/{JobID}/file

Payload

Name Type Format Description
name type JSON Required Description.

Response

Status Codes

Headers

Payload

Name Type Format Description
name type format description

Example

GET https://www.concursolutions.com/api/expense/extract/v1.0/nYoPK$pZmcowMRUqcl5bnDAwwsMydyt$xd/job/uIo87jk3SHudi$sdlYle8$peot$pD21jyd/file
Authorization: OAuth {token}

Request

HTTP/1.1 200 OK
Content-Type: text/csv
100,AAA,BBBB,CCCC,...<rest of file>

Response

HTTP/1.1 200 OK
Content-Type: application/zip
{ zip archive data}

Single file

Multiple files

Get an Array of Extract Jobs

Requests a list of the last 100 extract jobs ran for the specified Extract Definition.

Request

Headers

Parameters

Name Type Format Description
DefinitionID string - Required The definition identifier.
URI Template
https://www.concursolutions.com/api/expense/extract/v1.0/{DefinitionID}/job

Payload

Name Type Format Description
name type JSON Required Description.

Response

Status Codes

Headers

Payload

Jobs

Example

GET https://www.concursolutions.com/api/expense/extract/v1.0/nYoPK$pZmcowMRUqcl5bnDAwwsMydyt$xd/job HTTP/1.1
Authorization: OAuth {token}

Request

HTTP/1.1 200 OK
Content-Type: application/xml

Response

<jobs xmlns="...">
  <job>
    <id>https://www.concursolutions.com/api/expense/extract/v1.0/nYoPK$pZmcowMRUqcl5bnDAwwsMydyt$xd/job/uIo87jk3SHudi$sdlYle8$peot$pD21jyd</id>
    <status-link>https://www.concursolutions.com/api/expense/extract/v1.0/nYoPK$pZmcowMRUqcl5bnDAwwsMydyt$xd/job/uIo87jk3SHudi$sdlYle8$peot$pD21jyd/status</status-link>
    <start-time>2010-01-13T18:30:02Z</start-time>
    <status>Queued</status>
  </job>
  <job>
    <id>https://www.concursolutions.com/api/expense/extract/v1.0/nYoPK$pZmcowMRUqcl5bnDAwwsMydyt$xd/job/21UwwqA3jk25Lis77jF$piiD21c89lLwEq</id>
    <status-link>https://www.concursolutions.com/api/expense/extract/v1.0/nYoPK$pZmcowMRUqcl5bnDAwwsMydyt$xd/job/21UwwqA3jk25Lis77jF$piiD21c89lLwEq/status</status-link> 
    <start-time>2010-01-13T18:30:02Z</start-time>
    <stop-time>2010-01-13T18:30:50Z</stop-time>
    <status>Complete</status>
    <file-link>https://www.concursolutions.com/api/expense/extract/v1.0/nYoPK$pZmcowMRUqcl5bnDAwwsMydyt$xd/job/21UwwqA3jk25Lis77jF$piiD21c89lLwEq/file</file-link>
  </job>
  <job>
    <id>https://www.concursolutions.com/api/expense/extract/v1.0/nYoPK$pZmcowMRUqcl5bnDAwwsMydyt$xd/job/uI77ndy0Q1szuU73XSh56lshi$p215gHs1</id>
    <status-link>https://www.concursolutions.com/api/extract/v1.0/nYoPK$pZmcowMRUqcl5bnDAwwsMydyt$xd/job/uI77ndy0Q1szuU73XSh56lshi$p215gHs1/status</status-link>
    <start-time>2010-01-12T18:30:01Z</start-time>
    <stop-time>2010-01-12T18:31:01Z</stop-time>
    <status>Complete</status>
    <file-link>https://www.concursolutions.com/api/expense/extract/v1.0/nYoPK$pZmcowMRUqcl5bnDAwwsMydyt$xd/job/uI77ndy0Q1szuU73XSh56lshi$p215gHs1/file</file-link>
  </job>
</jobs>

Get a Single Extract Job

Retrieves the details of the specified extract definition.

Request

Headers

Parameters

Name Type Format Description
DefinitionID string - Required The identifier for the desired extract definition.
JobID string - Required The identifier for the job and the job keyword.
URI Template
https://www.concursolutions.com/api/expense/extract/v1.0/{DefinitionID}/job/{JobID}

Payload

None

Response

Status Codes

Headers

Payload

Job

Example

GET https://www.concursolutions.com/api/expense/extract/v1.0/nYoPK$pZmcowMRUqcl5bnDAwwsMydyt$xd/job/uIo87jk3SHudi$sdlYle8$peot$pD21jyd
Authorization: OAuth {token}

Request

HTTP/1.1 200 OK
Content-Type: application/xml

Response

<job xmlns="...">
  <id>https://www.concursolutions.com/api/expense/extract/v1.0/nYoPK$pZmcowMRUqcl5bnDAwwsMydyt$xd/job/uIo87jk3SHudi$sdlYle8$peot$pD21jyd></id>
  <status-link>https://www.concursolutions.com/api/extract/v1.0/nYoPK$pZmcowMRUqcl5bnDAwwsMydyt$xd/job/uIo87jk3SHudi$sdlYle8$peot$pD21jyd/status</status-link>
  <start-time>2010-01-12T18:30:01</start-time>
  <stop-time>2010-01-12T18:31:01</stop-time>
  <status>Complete</status>
  <file-link> https://www.concursolutions.com/api/expense/extract/v1.0/nYoPK$pZmcowMRUqcl5bnDAwwsMydyt$xd/job/uIo87jk3SHudi$sdlYle8$peot$pD21jyd/file</file-link>
</job>

Get a Single Extract Job Status

Retrieves the details of the specified extract definition.

Request

Headers

Parameters

Name Type Format Description
DefinitionID string - Required The identifier for the desired extract definition.
JobID string - Required The identifier for the job and the job keyword.
URI Template
https://www.concursolutions.com/api/expense/extract/v1.0/{DefinitionID}/job/{JobID}/status

Payload

None

Response

Status Codes

Headers

Payload

Job

Example

https://www.concursolutions.com/api/expense/extract/v1.0/nX8O9$pytn6vJEWvLOZxyy3GcNGyj0ZklG/job/nIJp1lR2R0LNT4XcO5fXG$s$sZmVuRTuG$ps/status
{Header}: {Value}

Request

HTTP/1.1 200 OK
Content-Type: application/xml

Response

<job xmlns="http://www.concursolutions.com/api/expense/extract/2010/02" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
  <id>https://www.concursolutions.com/api/expense/extract/v1.0/nX8O9$pytn6vJEWvLOZxyy3GcNGyj0ZklG/job/nIJp1lR2R0LNT4XcO5fXG$s$sZmVuRTuG$ps</id>
  <status-link>https://www.concursolutions.com/api/expense/extract/v1.0/nX8O9$pytn6vJEWvLOZxyy3GcNGyj0ZklG/job/nIJp1lR2R0LNT4XcO5fXG$s$sZmVuRTuG$ps/status</status-link>
  <start-time>2011-08-25T14:25:22.58</start-time>
  <stop-time>2011-08-25T14:25:23.537</stop-time>
  <status>Completed</status>
  <file-link>https://www.concursolutions.com/api/expense/extract/v1.0/nX8O9$pytn6vJEWvLOZxyy3GcNGyj0ZklG/job/nIJp1lR2R0LNT4XcO5fXG$s$sZmVuRTuG$ps/file</file-link>
</job>

Post an Extract Job Initiation Request

Initiates a new extract job for the specified extract definition. The job will be scheduled to start as soon as possible. The value will be Queued until the job begins.

Request

Headers

Parameters

Name Type Format Description
DefinitionID string - Required The identifier for the desired extract definition.
URI Template
https://www.concursolutions.com/api/expense/extract/v1.0/{DefinitionID}/job

Payload

Definition

Response

Status Codes

Headers

Payload

Job

Example

POST https://www.concursolutions.com/api/expense/extract/v1.0/nYoPK$pZmcowMRUqcl5bnDAwwsMydyt$xd/job
Authorization: OAuth {token}
Content-Type: application/xml

Request

HTTP/1.1 201 Created
Location: https://www.concursolutions.com/api/expense/extract/v1.0/nYoPK$pZmcowMRUqcl5bnDAwwsMydyt$xd/job/uIo87jk3SHudi$sdlYle8$peot$pD21jyd
Content-Type: application/xml
<definition xmlns="http://www.concursolutions.com/api/expense/extract/2010/02">
  <id>https://www.concursolutions.com/api/expense/extract/v1.0/nYoPK$pZmcowMRUqcl5bnDAwwsMydyt$xd</id>
</definition>

Response

<job xmlns="...">
  <id>https://www.concursolutions.com/api/expense/extract/v1.0/nYoPK$pZmcowMRUqcl5bnDAwwsMydyt$xd/job/uIo87jk3SHudi$sdlYle8$peot$pD21jyd</id>
  <status-link> https://www.concursolutions.com/api/expense/extract/v1.0/nYoPK$pZmcowMRUqcl5bnDAwwsMydyt$xd/job/uIo87jk3SHudi$sdlYle8$peot$pD21jyd/status</status-link>
  <start-time>2010-01-13T18:30:02Z</start-time>
  <status>Queued</status>
</job>

Schema

Definitions

Name Type Format Description
definitions array definition Required

Definition

Name Type Format Description
id string - The extract definition ID URI with encrypted ID.
job-link string - The extract job URI with encrypted ID. The job-link value is used as the URI when creating the extract job data request.
name string - The extract definition name.

Jobs

Name Type Format Description
jobs array job Required

Job

Name Type Format Description
id string - The unique job identifier with encrypted ID.
status-link string - A URI for retrieving the current job status, with encrypted ID. The status-link value is used as the URI when requesting the job status.
start-time string - The time in UTC (GMT) the job is scheduled to start.
stop-time string - The time in UTC (GMT) the job finished. Not included if the job is still running.
status string - The current status of the job.
file-link string - A URI for retrieving the file or files produced by the job run, with encrypted ID. Not included if the job is still running. The file-link value is used as the URI when retrieving the extract data.

Enterprise Resource Planning Integration

For the purposes of ERP integration this API is available to Professional Edition. For Standard Edition use Payment Batches v1 API ERP Integration.

  1. Get an array of extract definitions
    • Locate the desired definitions for your client. You may need to obtain additional details as there may be multiple files to obtain depending on client requirements.
    • Record the Definition ID to use in subsequent API requests.
  2. Get an array of extract jobs
    • OPTIONAL: the Partner only needs to do this if the Partner is running the job, otherwise skip this step.
    • Determine which jobs are interesting and record their file-link.
  3. Get an extract file or files

Lists v3

The Lists API allows you to view your configured lists within SAP Concur products, and create new lists. The lists are shared between multiple SAP Concur products. Use the List Items API to manage the items in the lists.

Lists v3 - Products and Editions

Lists v3 - Scope Usage

Name Description Endpoint
LIST Use and update lists configured by your company. GET, POST

Lists v3 - Get All Lists

Returns all lists based on the search criteria.

Parameters

Name Type Format Description
limit integer The default is 25 and the maximum is 100. Optional. The number of records to return.
offset string - Optional. The start of the page offset. The default is from the beginning.

Request

GET https://www.concursolutions.com/api/v3.0/common/lists HTTP/1.1
Host: www.concursolutions.com
Accept: application/json
 const headers = {
  'Accept':'application/json'

};

fetch('https://www.concursolutions.com/api/v3.0/common/lists',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

Response

200 Response

{
  "Items": {
    "ConnectorID": "string",
    "DisplayCodeFirst": true,
    "ExternalThreshold": 0,
    "ID": "string",
    "IsVendorList": true,
    "Name": "string",
    "SearchCriteriaCode": "string",
    "URI": "string"
  },
  "NextPage": "string"
}

Lists v3 - Create a New List

Creates a new list.

Parameters

Name Type Format Description
content ListPost - Required. List object to create.

Request

POST https://www.concursolutions.com/api/v3.0/common/lists HTTP/1.1
Host: www.concursolutions.com
Content-Type: application/json
Accept: application/json
const inputBody = '{
  "ConnectorID": "string",
  "DisplayCodeFirst": true,
  "ExternalThreshold": 0,
  "IsVendorList": true,
  "Name": "string",
  "SearchCriteriaCode": "string"
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json'

};

fetch('https://www.concursolutions.com/api/v3.0/common/lists',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

Response

200 Response

{
  "ID": "string",
  "URI": "string"
}

Get a Single List by ID

Returns a list by ID.

Parameters

Name Type Format Description
id string - Required.The unique identifier for the list.

Request

GET https://www.concursolutions.com/api/v3.0/common/lists/{id} HTTP/1.1
Host: www.concursolutions.com
Accept: application/json


const headers = {
  'Accept':'application/json'

};

fetch('https://www.concursolutions.com/api/v3.0/common/lists/{id}',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

Response

200 Response

{
  "ConnectorID": "string",
  "DisplayCodeFirst": true,
  "ExternalThreshold": 0,
  "ID": "string",
  "IsVendorList": true,
  "Name": "string",
  "SearchCriteriaCode": "string",
  "URI": "string"
}

Lists v3 - Update List

DEPRECATED: 05/19/2016 UNSUPPORTED: 11/19/2016. Updates list specified in the URL. Only the fields provided in the supplied object will be updated, missing fields will not be altered.

Parameters

Name Type Format Description
id string - Required. The unique identifier for the list.
content ListPut - Required. The list object to update.

Request

PUT https://www.concursolutions.com/api/v3.0/common/lists/{id} HTTP/1.1
Host: www.concursolutions.com
Content-Type: application/json
Accept: application/json

const inputBody = '{
  "DisplayCodeFirst": true,
  "Name": "string",
  "SearchCriteriaCode": "string"
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json'

};

fetch('https://www.concursolutions.com/api/v3.0/common/lists/{id}',
{
  method: 'PUT',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

Lists v3 - Schema

CreateResponse

Name Type Format Description
ID string -
URI string -

ListGet

Name Type Format Description
ConnectorID string - Optional. Defines the encrypted ConnectorID. If not provided then the list isn't associated with a connector.
DisplayCodeFirst Boolean - Required. Defines whether code should appear before text, or vice versa.
ExternalThreshold integer - Optional. Default value is 1. Defines the threshold from where the level starts being external. This value can only be set if a ConnectorID is provided.
ID string - The unique identifier of the resource.
IsVendorList Boolean - Required. Defines whether it is a vendor list.
Name string - Required. Defines a name for the list. This name must be unique.
SearchCriteriaCode string - Required. Defines whether the search criteria should apply to the code or to the text.
URI string - The URI to the resource.

ListGetCollection

Name Type Format Description
Items ListGet -
NextPage string - The URI of the next page of results, if any.

ListPost

Name Type Format Description
ConnectorID string - Optional. Defines the encrypted ConnectorID. If not provided then the list isn't associated with a connector.
DisplayCodeFirst Boolean - Required. Defines whether code should appear before text, or vice versa.
ExternalThreshold integer - Optional. Default value is 1. Defines the threshold from where the level starts being external. This value can only be set if a ConnectorID is provided.
IsVendorList Boolean - Required. Defines whether it is a vendor list.
Name string - Required. Defines a name for the list. This name must be unique.
SearchCriteriaCode string - Required. Defines whether the search criteria should apply to the code or to the text.

ListPut

Name Type Format Description
DisplayCodeFirst Boolean - Optional. Defines whether code should appear before text, or vice versa.
Name string - Optional. Defines a name for the list. This name must be unique.
SearchCriteriaCode string - Optional. Defines whether the search criteria should apply to the code or to the text.

List Item v3

The SAP Concur List Item API provides an automated solution to clients who would like to add, update, or delete list items. Use of the API is subject to some limitations on the volume of List data. You may need to manage the initial load of large volumes of data via a file import due to capacity limitations. This is also true if ongoing maintenance of List values involves a large volume.

Version

3.0

1.0 documentation is available here

Retrieve All List Items Based on the Search Criteria

GET /api/v3.0/common/listitems

Parameters

Name Type Format Description
limit Int32 query The number of records to return. The default is 25 and the maximum is 100.
offset string query The start of the page offset. The default is from the beginning.
listId string query The unique identifier for the list this item is a member.
name string query The name of the listItem. Text Max length: 64.
parentId string query The unique identifier of this item's parent. Is empty when there is no parent.
level1Code string query The item code for the first level of the list. All lists have at least a Level1Code. Text maximum 32 characters
level2Code string query The item code for the second level of the list. Empty when this level doesn't exist in the list. Text maximum 32 characters
level3Code string query The item code for the third level of the list. Empty when this level doesn't exist in the list. Text maximum 32 characters
level4Code string query The item code for the fourth level of the list. Empty when this level doesn't exist in the list. Text maximum 32 characters
level5Code string query The item code for the fifth level of the list. Empty when this level doesn't exist in the list. Text maximum 32 characters
level6Code string query The item code for the sixth level of the list. Empty when this level doesn't exist in the list. Text maximum 32 characters
level7Code string query The item code for the seventh level of the list. Empty when this level doesn't exist in the list. Text maximum 32 characters
level8Code string query The item code for the eighth level of the list. Empty when this level doesn't exist in the list. Text maximum 32 characters
level9Code string query The item code for the ninth level of the list. Empty when this level doesn't exist in the list. Text maximum 32 characters
level10Code string query The item code for the tenth level of the list. Empty when this level doesn't exist in the list. Text maximum 32 characters

Retrieve a List Item by ID

GET /api/v3.0/common/listitems/{id}

Parameters

Name Type Format Description
id string path Required The unique identifier for the listItem.
listId string query The unique identifier for the list this item is a member.

Create a New List Item

POST /api/v3.0/common/listitems

Parameters

Name Type Format Description
content - body Required List item object to create.

Update a List Item

PUT /api/v3.0/common/listitems/{id}

Parameters

Name Type Format Description
id string path Required The unique identifier for the list item.
content - body Required The list item object to update.

Delete a List Item

DELETE /api/v3.0/common/listitems/{id}

Parameters

Name Type Format Description
id string path Required The unique identifier of the listitem to delete
listId string query Required The unique identifier of the list associated with a listitem to be deleted

List Item v3 - Schema

List Items

Name Type Format Description
Items array List Item The result collection.
NextPage string - The URI of the next page of results, if any.

List Item

Name Type Format Description
ID string - The unique identifier of the resource.
Level10Code string - The item code for the tenth level of the list. Empty when this level doesn't exist in the list. Text maximum 32 characters
Level1Code string - The item code for the first level of the list. All lists have at least a Level1Code. Text maximum 32 characters
Level2Code string - The item code for the second level of the list. Empty when this level doesn't exist in the list. Text maximum 32 characters
Level3Code string - The item code for the third level of the list. Empty when this level doesn't exist in the list. Text maximum 32 characters
Level4Code string - The item code for the fourth level of the list. Empty when this level doesn't exist in the list. Text maximum 32 characters
Level5Code string - The item code for the fifth level of the list. Empty when this level doesn't exist in the list. Text maximum 32 characters
Level6Code string - The item code for the sixth level of the list. Empty when this level doesn't exist in the list. Text maximum 32 characters
Level7Code string - The item code for the seventh level of the list. Empty when this level doesn't exist in the list. Text maximum 32 characters
Level8Code string - The item code for the eighth level of the list. Empty when this level doesn't exist in the list. Text maximum 32 characters
Level9Code string - The item code for the ninth level of the list. Empty when this level doesn't exist in the list. Text maximum 32 characters
ListID string - The unique identifier for the list this item is a member.
Name string - The name of item. Text maximum 64 characters
ParentID string - The unique identifier of this item's parent. Is empty when there is no parent.
URI string - The URI to the resource.

Locations v3

Gets details of locations that are used by Concur and that are valid at the user's company.

Location v1.1 has been deprecated and can be found here.

Retrieve details of locations that are used by Concur and that are valid at the user's company

GET /api/v3.0/common/locations

Parameters

Name Type Format Description
offset string query The starting point of the next set of results, after the limit specified in the limit field has been reached.
limit Int32 query The number of records to return. Default value: 25
name string query A common name associated with the location. This name can be a location description such as a neighborhood (SoHo), a landmark (Statue of Liberty), or a city name (New York).
city string query The city name of the location.
countrySubdivision string query The ISO 3166-2:2007 country subdivision code for the location. Example: US-WA
country string query The 2-letter ISO 3166-1 country code for the location. Example: United States is US
administrativeRegion string query The administrative region of the location. An administrative region is a government unit, such as a county, that contains one or more cities.

Retrieve details of a specified location

GET /api/v3.0/common/locations/{id}

Parameters

Name Type Format Description
id string path Required The ID of the location.

Locations v3 - Schema

Locations

Name Type Format Description
Items Array Location The result collection.
NextPage string - The URI of the next page of results, if any.

Location

Name Type Format Description
AdministrativeRegion string - The administrative region of the location.
Country string - The 2-letter ISO 3166-1 country code for the location.
CountrySubdivision string - The ISO 3166-2:2007 country subdivision code for the location. Example: US-WA
IATACode string - The International Air Transport Association (IATA) airport code of the location.
ID string - The unique identifier of the resource.
IsAirport boolean - Indicates whether the location is an airport. Format: true or false
IsBookingTool boolean - Indicates whether the location is used by the booking tool. Format: true or false
Latitude Decimal - The latitude of the geocode for the location.
Longitude Decimal - The longitude of the geocode for the location.
Name string - The location name. Maximum length: 64 characters
URI string - The URI to the resource.

Suppliers v3

Supplier companies provide travel services to users. The Suppliers resource can be used to retrieve information about suppliers.

Retrieve all suppliers based on search criteria

GET /api/v3.0/common/suppliers/

Parameters

Name Type Format Description
name query string Name
address query string Address
address2 query string Address
city query string City
state query string State
zip query string Zip
country query string Country Code
phone query string Phone
mcCode query string MCC Code (Ex: Delta Airline - 3058)
taxId query string Tax Id
merchantType query string Merchant Type Code(Ex: Visa - VI, Amex - AX)
merchantID query string Merchant Id
iataCode query string IATA Code
relevance query Int32 Relevance of the Search results5

Retrieve a single supplier by ID

GET /api/v3.0/common/suppliers/{id}

Parameters

Name Type Format Description
id string path Required Supplier ID.

Suppliers v3 - Schema

Suppliers

Name Type Format Description
Items Array Supplier The result connection
NextPage string - The URI of the next page of results, if any.

Supplier

Name Type Format Description
AmadeusId string - Amadeus Id
AustinTetra string - Austin Tetra
BusinessName string - Name
ChainCode string - Chain Code
ChainName string - Chain Name
City string - City
CountryCode string - Country Code
CreditCardVendorId string - Creditcard Vendor Id
DunsNumber string - Duns Number
Email string - Email
Fax string - Fax
GalileoId string - Galileo Id
ID string - The unique identifier of the resource.
MccCode string - MCC Code (Ex: Delta Airline - 3058)
NorthstarId string - Northstar Id
PegasusId string - Pegasus Id
Phone string - Phone
PostalCode string - Zip
PrimaryNaics string - Primary Naics Code
PrimarySic string - Primary Sic Code
PropertyCode string - SUP_PARAM_PROPERTY_CODE
SabreId string - Sabre Id
SecondaryNaics string - Secondary Naics Code
SecondarySic string - Secondary Sic Code
State string - State
StreetAddress string - Address
StreetAddress2 string - Address2
TaxId string - Tax Id
TollFree string - Toll Free
URI string - The URI to the resource.
WebUrl string - Web Address
WorldspanId string - Worldspan Id

Direct Connect-Ground Transportation v.1

Direct Connect - Ground Transportation

The Ground Transportation Direct Connect provides a method for Travel users to access the inventory of ground transportation service providers. This direct connect was originally designed for use by limo service providers, but can be used with all forms of ground transportation.

Once the ground transportation supplier has developed their interface with SAP Concur, their inventory will begin appearing in ground transportation searches by opted-in Travel users.

This callout differs from the inbound SAP Concur web services in the following ways:

NOTE: This direct connect was originally designed to work with Limo providers, but can support all types of ground transportation.

Ground Transportation - Products and Editions

Ground Transportation - Product Restrictions

This direct connect is only available to Travel Suppliers with Ground Transportation inventory. This direct connect is not supported in the SAP Concur mobile application.

SAP Concur products are highly configurable, and not all clients will have access to all features.

Partner developers must determine which configurations are required for their solution prior to the review process.

Configuration Process

The configuration process has the following steps:

  1. The Travel Supplier creates the application on their system that will accept the requests from SAP Concur and return the appropriate responses.
  2. The Travel Supplier creates the endpoint on their system that SAP Concur uses to access their inventory.
  3. SAP Concur creates a production company for the travel supplier.
  4. The Travel Supplier registers their application with SAP Concur by logging in to their production company.
  5. SAP Concur configures Travel to send requests to the endpoint.
  6. The Travel client opts in to the Ground Transportation callout using the Travel Configuration UI to allow their users to view and book the available inventory. Clients must contact SAP Concur to have this setting activated

Once the configuration is complete, the callout uses the following process:

  1. The user searches for ground transportation when creating an itinerary in Travel.
  2. Travel sends the search details to the endpoint, using the Post Search Request.
  3. The supplier returns the search results.
  4. If the user chooses to reserve the ride, Travel sends the Post Sell Request.
  5. The supplier returns the Post Sell Reply.

This callout can also be used to perform the following operations:

Ground Transportation - Authentication

Authentication between SAP Concur and the application connector is performed using OAuth.

Operations

Cancel Reservation

Post Reservation Detail Search

Post Reservation Sell

Post Transportation Search

Update Reservation with the Supplier

Update Reservation with Travel

GDS Sell Formats

Sabre:
1 OTH LM 14MAY M GK1 DCA/PCI QA TEST/TEL 201 555 1212/RATE-$0.00/CONF-/PICKUP-209 MADISON ST SUITE 400 ALEXANDRIAVA 22314 AT 0900/DROPOFF-DCA AIRPORT AT 0915/203121365/RESERVATION L1

Apollo:
1 LIM ZM GK1  DCA 09MAY-/PCI QA TEST-TEL 2015551212/RATE-$0.00/CONF-/PICKUP-209 MADISON ST SUITE 400"ALEXANDRIA"VA"22314 AT 0900/DROPOFF-DCA AIRPORT/52695871/RESERVATION L1

Abacus:
1 OTH LM 14MAY M GK1 DCA/PCI QA TEST/TEL 201 555 1212/RATE-$0.00/CONF-/PICKUP-209 MADISON ST SUITE 400 ALEXANDRIAVA 22314 AT 0900/DROPOFF-DCA AIRPORT AT 0915/203121365/RESERVATION L1

Galileo:
TUR ZM AK1  SEA 15DEC-/FALCON DES-TEL 8666932526/RATE-50.00 HOURLY-2 HR MIN/CONF-/PU-18400  AT 0900/DO-SEA/771297634/RES

Amadeus:
2 MIS 1A HK1 LGA 13SEP-LMO CAPITAL LIMOUSINE/TEL-800 225 1656/RATE-USD24.00 FLAT/CONF-132625/PICKUP-55 WALL STREET NEW YORK NY 10005 AT 0530/DROPOFF- LGA AIRPORT AT 0600/RID-132625760

Cancel a reservation

The Cancel Reservation operation is sent to the supplier to cancel a travel reservation on behalf of a user. The Ground Transportation direct connect sends the relevant information to a URI that the travel supplier maintains. The standard location is: https://{servername}/concur/groundtransportation. This URI is configured by the supplier when registering the partner application.

Request

URI

/concur/groundtransportation

Headers

Content-Type header (optional)

Accept header (optional)

Authorization header (required)

The Authorization header must include Base64 encoded basic authentication credentials (login ID and password). The login and password are established when the application connector is registered.

'Authorization: Basic {Base64 encoded LoginID:Password}'

Request Body

The request contains a CC_LimoCancelRequest parent element with the child elements listed in the following table:

Element Required/Optional Description
ReservationID Required The unique identifier for the reservation.

Example Request

POST /concur/groundtransportation HTTPS/1.1
Host: example.com
Authorization: Basic ...
Content-Type: application/xml
Content-Length: {length of content body}

<CC_LimoCancelRequest>
    <ReservationID>1234</ReservationID>
</CC_LimoCancelRequest>

Response

The supplier responds to the request by supplying the full reservation details, with the updated status.

Content Type

Cancel A Reservation - Response Schema

The response will include a CC_LimoCancelReply parent element, with the following child elements:

Element Required? Description
Error Y The error information, if an error occurred. This parent element contains the following child elements:
ErrorCode: The code for the error. Will contain one of the following values:
400: Credential related error
800: Reservation cannot be cancelled
900: Unknown error
ErrorSource: The source of the error.
ErrorDescription:The additional error information.
ReservationID N The identifier for the reservation.
Status N The status of the reservation. The value will be one of the following:
XB: Cancellation Requested
XA: Cancellation Accepted
XD: Cancellation Declined
ConfNum N The confirmation number for the reservation.
CancelPolicy N The cancellation policy for the reservation.
CancelNum N The cancellation number for the reservation.
PrimaryPassenger Y The passenger contact name for the reservation. This parent element contains the following child elements:
FirstName: The contact's first name.
LastName: The contact's last name.
Phone: The contact's phone number.
Phone2: The contact's backup phone number.
CellPhone: The contact's cell phone number.
EmailAddress: The contact's email address.
ServiceType Y The type of service requested. Will contain one of the following values:
100: Point to point
110: One way to airport
111: One way from airport
120: One way to train station
121: One way from train station
200: Hourly
300: Airport to airport
ClassOfService N The requested service class. Will contain one of the following values:
100: Normal
200: High
300: Highest
If this value is not provided by the user, it will default to 100.
PickupLocation Y The pick up location. This parent element contains the following child elements:
LocationType: One of the following: 100 - Address, 200 - Airport, 300 - Train station.
Airport: Refer to the Airport Elements table. Provided if the LocationType = 200.
TrainStation: Refer to the Train Station Elements table. Provided if the LocationType = 300.
Address: The street address of the location. Provided if the LocationType = 100.
City: The location city.
State: The location state. Preferably 2 characters, max 10 characters.
Country: The location's 2 character ISO 3166-1 alpha-2 country code. Example: US
PostalCode: The location postal code.
ExtraNotes: Additional notes about the location. Example: Ring doorbell, Holiday Inn, etc.
DropoffLocation Y The drop off location. This parent element contains the following child elements:
LocationType: One of the following: 100 - Address, 200 - Airport, 300 - Train station, 400 - As directed.
Airport: Refer to the Airport Elements table. Provided if the LocationType = 200.
TrainStation: Refer to the Train Station Elements table. Provided if the LocationType = 300.
Address: The street address of the location. Provided if the LocationType = 100.
City: The location city.
State: The location state.
Country: The location's 2 character ISO 3166-1 alpha-2 country code. Example: US
PostalCode: The location postal code.
ExtraNotes: Additional notes about the location. Example: Apartment Building, gravel driveway, etc.
StartDateTime Y The time, in GMT, that the reservation must begin. Format: 2015-05-19T18:00:00
EndDateTime N The time, in GMT that the reservation will end. Provided for hourly reservations. Format: 2015-05-19T18:00:00
PickupInstructions N Additional instructions about the pick up request.
DropoffInstructions N Additional instructions about the drop off request.
LanguageCode Y The language of the traveler. Will be one of the following options:
en: English
en-us: English (US)
en-gb: English (UK)
fr: French
fr-ca: French (Canadian)
de: German
pt: Portuguese
es: Spanish
nl: Dutch
it: Italian
ja: Japanese
pl: Polish
pt-br: Portuguese (Brazilian)
ru: Russian
hu: Hungarian
ko: Korean
sv: Swedish
zh-cn: Chinese
zh-tw: Traditional Chinese
Currency Y The 3-letter ISO 4217 currency code for the reservation amount.
NumPassengers N The number of passengers.
RequestedDriver N The name of the requested driver, if available.
SpecialServiceRequest N The details of the special service request, if available.
PickupServiceArrangement N The details of the pickup arrangement, if available.
DropoffServiceArrangement N The details of the dropoff arrangement, if available.
ExtraStopArrangement N The details of the extra stop arrangement, if available.
RateInfo Y The booked rate details. Refer to the Rate Information Elements table for more information.
Vehicle Y The vehicle details. This parent element contains the following child elements:
VehicleType: One of the following values:
100: Sedan
200: Limo
250: Stretch Limo
300: SUV
350: Stretch SUV
400: Van
450: Mini-Bus
500: Motor Coach
600: Shuttle
700: Trolley
800: Carriage
900: Any
Description: The vehicle description.
MaxPassengers: The maximum number of passengers for the vehicle. Must be greater than zero.
VehicleID: Information to identify the specific vehicle.
Vendor Y The reservation vendor. This parent element contains the following child elements:
VendorCode: The vendor code for the vendor.
VendorName: The vendor's name.
PhoneNumber: The vendor's phone number.
FormOfPayment Y The form of payment for the reservation. This parent element contains one of the following child elements:
CreditCard: If present, the passenger will pay with credit card. Refer to the Reply Credit Card Elements table for the child elements.
Cash: If present, the passenger will pay cash.
Check: If present, the passenger will pay with a check.
DirectBilling: If present, the passenger will pay through direct billing.
RateDisclaimer N Disclaimer text about the rate.
ProviderFeedback N Any additional feedback from the supplier.
AccountingInfo N The accounting information for the reservation. This parent element contains the following child elements:
AccountingField1 through AccountingField5: These fields contain detailed accounting information.

Rate Information Elements

Element Required? Description
RateID Y The rate identifier.
Rate Y The BasePrice + ServiceCharge + SurCharge + Tax
RateTypeCode Y The code for the rate type. Will be one of the following options:
F: Flat rate
H: Hourly
E: Estimated amount
N: Currently not available
CategoryCode N Extra information that will be passed back during sell request to help identify the rate.
Currency Y The 3-letter ISO 4217 currency code for the rate amount.
NoRateText N Explanation of rate type. Provided if RateTypeCode = N
MinHours N The minimum number of hours for the reservation.
DiscountType N The type of discount applied.
BasePrice N The reservation price without taxes, surcharges or service charges.
ServiceCharge N The service charge for the reservation.
SurCharge N This element contains the desc attribute, with text describing the reason for the surcharge. Example: <SurCharge desc="fuel">
Tax N The reservation tax.
ExtraPickupCharge N Any additional fees for the pickup service.
ExtraDropoffCharge N Any additional fees for the dropoff service.
OptionalExtraStopCharge N The charge for any additional stops.
OptionalExtraTimeCharge N The charge for each additional hour.

Reply Credit Card Elements

Element Required? Description
Type Y The card type.
Number Y The card number.
Expiration Y The card expiration date. Format: 2013-02-19

Cancel A Reservation - Example of Successful Response

HTTPS/1.1 200 OK
Content-Type: application/xml
Content-Length: {length of content body}

<CC_LimoCancelReply>
    <Error>
        <ErrorCode />
        <ErrorSource />
        <ErrorDescription />
    </Error>
    <ReservationID>1234</ReservationID>
    <Status>XB</Status>
    <ConfNum>4444</ConfNum>
    <CancelPolicy />
    <CancelNum>55555</CancelNum>
    <PrimaryPassenger>
        <FirstName>Chris</FirstName>
        <LastName>Miller</LastName>
        <Phone>5551234567</Phone>
        <Phone2>5551234568</Phone2>
        <CellPhone>5551234569</CellPhone>
        <EmailAddress>cmiller@example.com</EmailAddress>
    </PrimaryPassenger>
    <ServiceType>110</ServiceType>
    <ClassOfService />
    <PickupLocation>
        <LocationType>100</LocationType>
        <Airport>
            <AirportCode />
            <Flight>
                <CarrierCode />
                <FlightNumber />
                <ArrivalDateTime />
            </Flight>
        </Airport>
        <TrainStation>
            <StationCode />
            <StationName />
            <City />
            <State />
            <Train>
                <CarrierCode />
                <CarrierName />
                <TrainNumber />
                <ArrivalDateTime />
            </Train>
        </TrainStation>
        <Address>209 Madison St</Address>
        <City>Alexandria</City>
        <State>VA</State>
        <Country>US</Country>
        <PostalCode>22314</PostalCode>
        <ExtraNotes />
    </PickupLocation>
    <DropoffLocation>
        <LocationType>200</LocationType>
        <Airport>
            <AirportCode>DCA</AirportCode>
            <Flight>
                <CarrierCode>UA</CarrierCode>
                <FlightNumber>333</FlightNumber>
                <DepartureDateTime>2012-02-19T11:29:00</DepartureDateTime>
            </Flight>
        </Airport>
        <TrainStation>
            <StationCode />
            <StationName />
            <City />
            <State />
            <Train>
                <CarrierCode />
                <CarrierName />
                <TrainNumber />
                <DepartureDateTime />
            </Train>
        </TrainStation>
        <Address />
        <City />
        <State />
        <Country />
        <PostalCode />
        <ExtraNotes />
    </DropoffLocation>
    <StartDateTime>2012-02-19T09:00:00</StartDateTime>
    <EndDateTime />
    <PickupInstructions>pick me up</PickupInstructions>
    <DropoffInstructions>None</DropoffInstructions>
    <LanguageCode>en-us</LanguageCode>
    <Currency>USD</Currency>
    <NumPassengers>1</NumPassengers>
    <RequestedDriver />
    <SpecialServiceRequest />
    <PickupServiceArrangement />
    <DropoffServiceArrangement />
    <ExtraStopArrangement />
    <RateInfo>
        <RateID>5</RateID>
        <Rate>42.50</Rate>
        <RateTypeCode>E</RateTypeCode>
        <CategoryCode />
        <MinHours />
        <Currency>US</Currency>
        <NoRateText />
        <DiscountType />
        <BasePrice>35.00</BasePrice>
        <ServiceCharge>5.00</ServiceCharge>
        <SurCharge desc="fuel">1.00</SurCharge>
        <Tax>1.50</Tax>
        <ExtraPickupCharge />
        <ExtraDropoffCharge />
        <OptionalExtraStopCharge />
        <OptionalExtraTimeCharge />
        <Message />
    </RateInfo>
    <RateDisclaimer />
    <Vehicle>
        <VehicleType>100</VehicleType>
        <Description>This is a Sedan.</Description>
        <MaxPassengers>1</MaxPassengers>
        <VehicleID>12</VehicleID>
    </Vehicle>
    <Vendor>
        <VendorCode>LML</VendorCode>
        <VendorName>LimoVendor</VendorName>
        <PhoneNumber>4354654654</PhoneNumber>
    </Vendor>
    <ProviderFeedback />
    <FormOfPayment>
        <Cash />
        <Check />
        <DirectBilling />
        <CreditCard>
            <Type>VI</Type>
            <Number>XXXXXXXXXXXX1111</Number>
            <Expiration>2013-02-19</Expiration>
        </CreditCard>
    </FormOfPayment>
    <AccountingInfo>
        <AccountingField1>715</AccountingField1>
        <AccountingField2>temp@outtask.com</AccountingField2>
        <AccountingField3>11</AccountingField3>
        <AccountingField4>Development</AccountingField4>
        <AccountingField5/>
    </AccountingInfo>
</CC_LimoCancelReply>

Post a reservation detail search

Request

The following request is sent to the supplier when the Travel user selects a ground transportation reservation to get additional details.

URI

The Ground Transportation direct connect sends the relevant information to a URI that the travel supplier maintains. The standard location is:

https://{servername}/concur/groundtransportation

The URI is configured by the supplier when registering the partner application.

Request Headers - Required

Authorization header with OAuth credentials. Refer to the OAuth documentation for more information.

Request Headers - Optional

None

Request Body

The request will contain a CC_LimoReservationDetailRequest parent element, containing the following child element:

Element Name Required/Optional Data Type Description
ReservationID The unique identifier for the reservation. Returned in the ReservationID element by the response of the Post Reservation Sell function.

XML Example Request

POST /concur/groundtransportation HTTPS/1.1
Host: example.com
Authorization: Basic ...
Content-Type: application/xml
Content-Length: {length of content body}
<CC_LimoReservationDetailRequest>
 <ReservationID>1234</ReservationID>
</CC_LimoReservationDetailRequest>

Response

The supplier responds to the request by supplying the full reservation details.

Content Type

application/xml

Post a reservation detail search - Response Schema

The response will include a CC_LimoReservationDetailReply parent element, with the following child elements:

Element Name Required/Optional Data Type Description
Error Y The error information, if an error occurred. For information about the child elements of this parent element, see the Error elements table.
ReservationID N The identifier for the reservation.
Status N The status of the reservation. The value will be one of the following:
RB: Reservation Pending
RA: Reservation Accepted (Reserved)
RD: Reservation Declined
XB: Cancellation Pending
XA: Cancellation Confirmed (Cancelled)
XD: Cancellation Declined
ConfNum N The confirmation number for the reservation.
CancelPolicy N The cancellation policy for the reservation.
CancelNum N The cancellation number for the reservation.
PrimaryPassenger Y The passenger contact name for the reservation. For information about the child elements of this parent element, see the PrimaryPassenger elements table.
ServiceType Y The type of service requested. Will contain one of the following values:
100: Point to point
110: One way to airport
111: One way from airport
120: One way to train station
121: One way from train station
200: Hourly
300: Airport to airport
ClassOfService N The requested service class. Will contain one of the following values:
100: Normal
200: High
300: Highest
If this value is not provided by the user, it will default to 100.
PickupLocation Y The pick up location. For information about the child elements of this parent element, see the PickupLocation elements table.
DropoffLocation Y The drop off location. For information about the child elements of this parent element, see the DropoffLocation elements table.
StartDateTime Y The time, in GMT, that the reservation must begin. Format: 2015-05-19T18:00:00
EndDateTime N The time, in GMT that the reservation will end. Provided for hourly reservations. Format: 2015-05-19T18:00:00
PickupInstructions N Additional instructions about the pick up request.
DropoffInstructions N Additional instructions about the drop off request.
LanguageCode Y The language of the traveler. Will be one of the following options:
en: English
en-us: English (US)
en-gb: English (UK)
fr: French
fr-ca: French (Canadian)
de: German
pt: Portuguese
es: Spanish
nl: Dutch
it: Italian
ja: Japanese
pl: Polish
bt-br: Portuguese (Brazilian)
ru: Russian
hu: Hungarian
ko: Korean
sv: Swedish
zh-cn: Chinese
zh-tw: Traditional Chinese
Currency Y The 3-letter ISO 4217 currency code for the reservation amount.
NumPassengers N The number of passengers.
RequestedDriver N The name of the requested driver, if available.
SpecialServiceRequest N The details of the special service request, if available.
PickupServiceArrangement N The details of the pickup arrangement, if available.
DropoffServiceArrangement N The details of the dropoff arrangement, if available.
ExtraStopArrangement N The details of the extra stop arrangement, if available.
RateInfo Y The booked rate details. Refer to the Rate Information elements table for more information.
Vehicle Y The vehicle details. For information about the child elements of this parent element, see the Vehicle elements table.
Vendor Y The reservation vendor. For information about the child elements of this parent element, see the Vendor elements table.
FormOfPayment Y The form of payment for the reservation. For information about the child elements of this parent element, see the FormOfPayment elements table.
RateDisclaimer N Disclaimer text about the rate.
ProviderFeedback N Any additional feedback from the supplier.
AccountingInfo N The accounting information for the reservation. This parent element contains the following child elements: AccountingField1 through AccountingField5

Error Child Elements

Element Name Required/Optional Data Type Description
ErrorCode The code for the error. Will contain one of the following values:
400: Credential related error
700: Reservation not available
900: Unknown error
ErrorSource The source of the error.
ErrorDescription The additional error information.

PrimaryPassenger Child Element

Element Name Required/Optional Data Type Description
FirstName The contact's first name.
LastName The contact's last name.
Phone The contact's phone number.
Phone2 The contact's backup phone number.
CellPhone The contact's cell phone number.
EmailAddress The contact's email address.

PickupLocation

Element Name Required/Optional Data Type Description
LocationType One of the following: 100 - Address, 200 - Airport, 300 - Train station.
Airport Refer to the Airport elements table. Provided if the LocationType = 200.
TrainStation Refer to the Train Station elements table. Provided if the LocationType = 300.
Address The street address of the location. Provided if the LocationType = 100.
City The location city.
State The location state. Preferably 2 characters, max 10 characters.
Country The location's 2 character ISO 3166-1 alpha-2 country code. Example: US
PostalCode The location postal code.
ExtraNotes Additional notes about the location. Example: Ring doorbell, Holiday Inn, etc.

DropoffLocation

Element Name Required/Optional Data Type Description
LocationType One of the following: 100 - Address, 200 - Airport, 300 - Train station, 400 - As directed.
Airport Refer to the Airport elements table. Provided if the LocationType = 200.
TrainStation Refer to the Train Station elements table. Provided if the LocationType = 300.
Address The street address of the location. Provided if the LocationType = 100.
City The location city.
State The location state. Preferably 2 characters, max 10 characters.
Country The location's 2 character ISO 3166-1 alpha-2 country code. Example: US
PostalCode The location postal code.
ExtraNotes Additional notes about the location. Example: Apartment Building, gravel driveway, etc.

Vehicle Child Elements

Element Name Required/Optional Data Type Description
VehicleType One of the following values:
100: Sedan
200: Limo
250: Stretch Limo
300: SUV
350: Stretch SUV
400: Van
450: Mini-Bus
500: Motor Coach
600: Shuttle
700: Trolley
800: Carriage
900: Any
Description The vehicle description.
MaxPassengers The maximum number of passengers for the vehicle. Must be greater than zero.
VehicleID Information to identify the specific vehicle.

Vendor Child Elements

Element Name Required/Optional Data Type Description
VendorCode The vendor code for the vendor.
VendorName The vendor's name.
PhoneNumber The vendor's phone number.

FormOfPayment Child Elements

Element Name Required/Optional Data Type Description
CreditCard If present, the passenger will pay with credit card. Refer to the Reply Credit Card Elements table for the child elements.
Cash If present, the passenger will pay cash.
Check If present, the passenger will pay with a check.
DirectBilling If present, the passenger will pay through direct billing.

Post a reservation - Rate Information Elements

Element Name Required/Optional Data Type Description
RateID Y The rate identifier.
Rate Y The BasePrice + ServiceCharge + SurCharge + Tax
RateTypeCode Y The code for the rate type. Will be one of the following options:
F: Flat rate
H: Hourly
E: Estimated amount
N: Currently not available
CategoryCode N Extra information that will be passed back during sell request to help identify the rate.
Currency Y The 3-letter ISO 4217 currency code for the rate amount.
NoRateText N Explanation of rate type. Provided if RateTypeCode = N
MinHours N The minimum number of hours for the reservation.
DiscountType N The type of discount applied.
BasePrice N The reservation price without taxes, surcharges or service charges.
ServiceCharge N The service charge for the reservation.
SurCharge N This element contains the desc attribute, with text describing the reason for the surcharge. Example: <SurCharge desc="fuel">
Tax N The reservation tax.
ExtraPickupCharge N Any additional fees for the pickup service.
ExtraDropoffCharge N Any additional fees for the drop off service.
OptionalExtraStopCharge N The charge for any additional stops.
OptionalExtraTimeCharge N The charge for each additional hour.

Post a reservation - Reply Credit Card Elements

Element Name Required/Optional Data Type Description
Type Y The card type.
Number Y The card number.
Expiration Y The card expiration date. Format: 2013-02-19.

Airport Elements

Element Name Required/Optional Data Type Description
AirportCode The IATA code for the airport.
Flight The flight information. For information about the child elements of this parent element, see the Flight elements table.

Flight Child Elements

Element Name Required/Optional Data Type Description
CarrierCode The airline code.
FlightNumber The flight number.
ArrivalDateTime The flight arrival time. Only provided for the PickupLocation element. Format: 2015-05-19T18:00:00
DepartureDateTime The flight departure time. Only provided for the DropoffLocation element. Format: 2015-05-19T18:00:00

Train Station Elements

Element Name Required/Optional Data Type Description
StationCode The station code.
StationName The name of the station.
City The city the station is located in.
State The state the station is located in. Preferably 2 characters, max 10 characters.
Train The train information. For information about the child elements of this parent element, see the Train elements table.

Train Child Elements

Element Name Required/Optional Data Type Description
CarrierCode The code of the train carrier.
CarrierName The name of the train carrier.
TrainNumber The train number.
ArrivalDateTime The train arrival time. Only provided for the PickupLocation element. Format: 2015-05-19T18:00:00
DepartureDateTime The train departure time. Only provided for the DropoffLocation element. Format: 2015-05-19T18:00:00

Post Reservation - XML Example of Successful Response

HTTPS/1.1 200 OK
Content-Type: application/xml
Content-Length: {length of content body}
<CC_LimoReservationDetailReply>
  <Error>
    <ErrorCode />
    <ErrorSource />
    <ErrorDescription />
  </Error>
  <ReservationID>1234</ReservationID>
  <Status>RB</Status>
  <ConfNum>4444</ConfNum>
  <CancelPolicy />
  <CancelNum>55555</CancelNum>
  <PrimaryPassenger>
    <FirstName>Chris</FirstName>
    <LastName>Miller</LastName>
    <Phone>5551234567</Phone>
    <Phone2>5551234568</Phone2>
    <CellPhone>5551234569</CellPhone>
    <EmailAddress>cmiller@example.com</EmailAddress>
  </PrimaryPassenger>
  <ServiceType>110</ServiceType>
  <ClassOfService />
  <PickupLocation>
    <LocationType>100</LocationType>
    <Airport>
      <AirportCode />
      <Flight>
        <CarrierCode />
        <FlightNumber />
        <ArrivalDateTime />
      </Flight>
    </Airport>
    <TrainStation>
      <StationCode />
      <StationName />
      <City />
      <State />
      <Train>
        <CarrierCode />
        <CarrierName />
        <TrainNumber />
        <ArrivalDateTime />
      </Train>
    </TrainStation>
    <Address>209 Madison St</Address>
    <City>Alexandria</City>
    <State>VA</State>
    <Country>US</Country>
    <PostalCode>22314</PostalCode>
    <ExtraNotes />
  </PickupLocation>
  <DropoffLocation>
    <LocationType>200</LocationType>
    <Airport>
      <AirportCode>DCA</AirportCode>
      <Flight>
        <CarrierCode>UA</CarrierCode>
        <FlightNumber>333</FlightNumber>
        <DepartureDateTime>2012-02-19T11:29:00</DepartureDateTime>
      </Flight>
    </Airport>
    <TrainStation>
      <StationCode />
      <StationName />
      <City />
      <State />
      <Train>
        <CarrierCode />
        <CarrierName />
        <TrainNumber />
        <DepartureDateTime />
      </Train>
    </TrainStation>
    <Address />
    <City />
    <State />
    <Country />
    <PostalCode />
    <ExtraNotes />
  </DropoffLocation>
  <StartDateTime>2012-02-19T09:00:00</StartDateTime>
  <EndDateTime />
  <PickupInstructions>pick me up</PickupInstructions>
  <DropoffInstructions>None</DropoffInstructions>
  <LanguageCode>en-us</LanguageCode>
  <Currency>USD</Currency>
  <NumPassengers>1</NumPassengers>
  <RequestedDriver />
  <SpecialServiceRequest />
  <PickupServiceArrangement />
  <DropoffServiceArrangement />
  <ExtraStopArrangement />
  <RateInfo>
    <RateID>5</RateID>
    <Rate>42.50</Rate>
    <RateTypeCode>E</RateTypeCode>
    <CategoryCode />
    <MinHours />
    <Currency>USD</Currency>
    <NoRateText />
    <DiscountType />
    <BasePrice>35.00</BasePrice>
    <ServiceCharge>5.00</ServiceCharge>
    <SurCharge desc="fuel">1.00</SurCharge>
    <Tax>1.50</Tax>
    <ExtraPickupCharge />
    <ExtraDropoffCharge />
    <OptionalExtraStopCharge />
    <OptionalExtraTimeCharge />
    <Message />
  </RateInfo>
  <RateDisclaimer />
  <Vehicle>
    <VehicleType>100</VehicleType>
    <Description>This is a Sedan.</Description>
    <MaxPassengers>1</MaxPassengers>
    <VehicleID>12</VehicleID>
  </Vehicle>
  <Vendor>
    <VendorCode>LML</VendorCode>
    <VendorName>LimoVendor</VendorName>
    <PhoneNumber>4354654654</PhoneNumber>
  </Vendor>
  <ProviderFeedback />
  <FormOfPayment>
    <Cash />
    <Check />
    <DirectBilling />
    <CreditCard>
      <Type>VI</Type>
      <Number>XXXXXXXXXXXX1111</Number>
      <Expiration>2013-02-19</Expiration>
    </CreditCard>
  </FormOfPayment>
  <AccountingInfo>
    <AccountingField1>715</AccountingField1>
    <AccountingField2>temp@outtask.com</AccountingField2>
    <AccountingField3>11</AccountingField3>
    <AccountingField4>Development</AccountingField4>
    <AccountingField5/>
  </AccountingInfo>
</CC_LimoReservationDetailReply>

Post a reservation sell request

A post reservation sell request is sent when a Travel user attempts to book a ground transportation reservation.

Post A Reservation Sell Request - Request

Supported Accept Types

application/xml

Request URI

The Ground Transportation direct connect sends the relevant information to a URI that the travel supplier maintains. The standard location is:

https://{servername}/concur/groundtransportation

The URI is configured by the supplier when registering the partner application.

Headers

Authorization Header

Authentication header with Base64 encoded basic authentication credentials (login ID and password) is required. The basic authentication credentials are established during the application review process.

Authorization: Basic {Base64 encoded LoginID:Password}

Post Reservation - Request Body

The request will contain a CC_LimoSellRequest parent element, containing the following child elements.

CorporateClient

The corporate client the booking is on behalf of. This parent element contains the following child element:

Booker

The user booking the reservation. This parent element contains the following child elements:

PrimaryPassenger

The passenger contact name for the reservation. This parent element contains the following child elements:

ServiceType

The type of service requested. Will contain one of the following values:

ClassOfService

The requested service class. Will contain one of the following values:

If this value is not provided by the user, it will default to 100

PickupLocation

The pick up location. This parent element contains the following child elements:

DropoffLocation

The drop off location. This parent element contains the following child elements:

StartDateTime

The time, in GMT, that the reservation must begin. Format: 2015-05-19T18:00:00

EndDateTime

The time, in GMT that the reservation will end. Provided for hourly reservations. Format: 2015-05-19T18:00:00

PickupInstructions

Additional instructions about the pick up request.

DropoffInstructions

Additional instructions about the drop off request.

LanguageCode

The language of the traveler. Will be one of the following options:

Currency

The 3-letter ISO 4217 currency code for the reservation amount.

NumPassengers

The number of passengers.

DiscountCode

The discount code information. This parent element contains the following child elements:

RateInfo

The booked rate. This parent element contains the following child elements:

Vehicle

The vehicle details. This parent element contains the following child elements:

Vendor

The reservation vendor. This parent element contains the following child element:

FormOfPayment

The form of payment for the reservation. This parent element contains one of the following child elements:

RequestedDriver

The name of the requested driver, if available.

SpecialServiceRequest

The details of the special service request, if available.

PickupServiceArrangement

The details of the pickup arrangement, if available.

DropoffServiceArrangement

The details of the dropoff arrangement, if available.

ExtraStopArrangement

The details of the extra stop arrangement, if available.

RequestedDriver

The name of the requested driver, if available.

Post Reservation - Airport Elements

AirportCode

The IATA code for the airport.

Flight: The flight information. This parent element contains the following child elements: * CarrierCode: The airline code. * FlightNumber: The flight number. * ArrivalDateTime: The flight arrival time. Only provided for the PickupLocation element. Format: 2015-05-19T18:00:00 * DepartureDateTime: The flight departure time. Only provided for the DropoffLocation element. Format: 2015-05-19T18:00:00

Post Reservation - Train Station Elements

StationCode

The station code.

StationName

The name of the station.

City

The city the station is located in.

State

The state the station is located in. Preferably 2 characters, max 10 characters.

Train

The train information. This parent element contains the following child elements:

Post A Reservation Sell Request - Credit Card Elements

Type

The card type.

Number

The card number.

Expiration

The card expiration date. Format: 2013-02-19

Name

The name on the card.

Address

The street information of the billing address of the car.

City

The city of the billing address of the car.

State

The state of the billing address of the car. Preferably 2 characters, max 10 characters.

Country

The country of the billing address of the car.

PostalCode

The postal code of the billing address of the car.

Post A Reservation Sell - XML Example Request

POST /concur/groundtransportation HTTPS/1.1
Host: example.com
Authorization: Basic ...
Content-Type: application/xml
Content-Length: {length of content body}

<CC_LimoSellRequest>
  <CorporateClient>
      <CompanyCode>339</CompanyCode>
  </CorporateClient>
  <Booker>
      <UserID>55414</UserID>
      <EmailAddress>cmiller@example.com</EmailAddress>
      <Phone>5551234567</Phone>
  </Booker>
  <PrimaryPassenger>
      <FirstName>Chris</FirstName>
      <LastName>Miller</LastName>
      <Phone>5551234567</Phone>
      <Phone2>5551234568</Phone2>
      <CellPhone>5551234569</CellPhone>
      <EmailAddress>cmiller@example.com</EmailAddress>
  </PrimaryPassenger>
  <ServiceType>110</ServiceType>
  <ClassOfService>100</ClassOfService>
  <StartDateTime>2012-02-19T09:00:00</StartDateTime>
  <EndDateTime />
  <PickupInstructions>pick me up</PickupInstructions>
  <DropoffInstructions>None</DropoffInstructions>
  <LanguageCode>en-us</LanguageCode>
  <RateInfo>
      <RateID>1</RateID>
      <Rate>42.50</Rate>
      <RateTypeCode>100</RateTypeCode>
      <CategoryCode />
      <Currency>USD</Currency>
  </RateInfo>
  <Vehicle>
      <VehicleType>Sedan</VehicleType>
      <Description>This is a Sedan.</Description>
      <MaxPassengers>1</MaxPassengers>
      <VehicleID>12</VehicleID>
  </Vehicle>
  <Vendor>
      <VendorCode>LML</VendorCode>
      <VendorName>LimoVendor</VendorName>
      <PhoneNumber>4354654654</PhoneNumber>
  </Vendor>
  <FormOfPayment>
      <CreditCard>
          <Type>VI</Type>
          <Number>xxxxxxxxxxxx1111</Number>
          <Expiration>2013-02-19</Expiration>
          <NameOnCard />
          <Address>209 MADISON ST. #400</Address>
          <City>ALEXANDRIA</City>
          <State>VA</State>
          <Country>US</Country>
          <PostalCode>22314</PostalCode>
      </CreditCard>
  </FormOfPayment>
  <RequestedDriver />
  <AccountingInfo>
      <AccountingField1>715</AccountingField1>
      <AccountingField2>temp@outtask.com</AccountingField2>
      <AccountingField3>11</AccountingField3>
      <AccountingField4>Development</AccountingField4>
      <AccountingField5/>
  </AccountingInfo>
</CC_LimoSellRequest>

Post Reservation - Response

The supplier responds to the Sell request by returning the details of the booked reservation.

Supported Content Types

application/xml

Post Reservation - Content Body

The response will include a CC_LimoSellReply parent element, with the following child elements:

Element Required? Description
Error Y The error information, if an error occurred. For information about the child elements of this parent element, see the Error elements table below.
ReservationID N The identifier for the reservation.
Status N The status of the reservation. The value will be one of the following:
RB: Reservation Pending
RA: Reservation Accepted (Reserved)
RD: Reservation Declined
ConfNum N The confirmation number for the reservation.
CancelPolicy N The cancellation policy for the reservation.
CancelNum N The cancellation number for the reservation.
PrimaryPassenger Y The passenger contact name for the reservation. For information about the child elements of this parent element, see the PrimaryPassenger elements table below.
ServiceType Y The type of service requested. Will contain one of the following values:
100: Point to point
110: One way to airport
111: One way from airport
120: One way to train station
121: One way from train station
200: Hourly
300: Airport to airport
ClassOfService N The requested service class. Will contain one of the following values:
100: Normal
200: High
300: Highest

If this value is not provided by the user, it will default to 100.
PickupLocation Y The pick up location. For information about the child elements of this parent element, see the PickupLocation elements table below.
DropoffLocation Y The drop off location. For information about the child elements of this parent element, see the DropoffLocation elements table below.
StartDateTime Y The time, in GMT, that the reservation must begin. Format: 2015-05-19T18:00:00
EndDateTime N The time, in GMT that the reservation will end. Provided for hourly reservations. Format: 2015-05-19T18:00:00
PickupInstructions N Additional instructions about the pick up request.
DropoffInstructions N Additional instructions about the drop off request.
LanguageCode Y The language of the traveler. Will be one of the following options:
en: English
en-us: English (US)
en-gb: English (UK)
fr: French
fr-ca: French (Canadian)
de: German
pt: Portuguese
es: Spanish
nl: Dutch
it: Italian
ja: Japanese
pl: Polish
pt-br: Portuguese (Brazilian)
ru: Russian
hu: Hungarian
ko: Korean
sv: Swedish
zh-cn: Chinese
zh-tw: Traditional Chinese
Currency Y The 3-letter ISO 4217 currency code for the reservation amount.
NumPassengers N The number of passengers.
RequestedDriver N The name of the requested driver, if available.
SpecialServiceRequest N The details of the special service request, if available.
PickupServiceArrangement N The details of the pickup arrangement, if available.
DropoffServiceArrangement N The details of the dropoff arrangement, if available.
ExtraStopArrangement N The details of the extra stop arrangement, if available.
RateInfo Y The booked rate details. Refer to the Rate Information elements table below for more information.
Vehicle Y The vehicle details. For information about the child elements of this parent element, see the Vehicle elements table below.
Vendor Y The reservation vendor. For information about the child elements of this parent element, see the Vendor elements table below.
FormOfPayment Y The form of payment for the reservation. For information about the child elements of this parent element, see the FormOfPayment elements table below.
RateDisclaimer N Disclaimer text about the rate.
ProviderFeedback N Any additional feedback from the supplier.
AccountingInfo N The accounting information for the reservation. This parent element contains one or more AccountingField elements: AccountingField1 through AccountingField5. These fields contain detailed accounting information.

Post A Reservation Sell Request - Error Elements

Element Description
ErrorCode The code for the error. Will contain one of the following values:
100: Pickup/dropoff location related error
200: Pickup/dropoff time related error
300: Other request parameters related error
400: Credential related error
500: No rate/service available
600: FOP related error
900: Unknown error
ErrorSource The source of the error.
ErrorDescription The additional error information.

PrimaryPassenger Elements

Element Description
FirstName The contact's first name.
LastName The contact's last name.
Phone The contact's phone number.
Phone2 The contact's backup phone number.
CellPhone The contact's cell phone number.
EmailAddress The contact's email address.

Post Reservation - Rate Information Elements

Element Name Required? Data Type Description
RateID Y The rate identifier.
Rate Y The BasePrice + ServiceCharge + SurCharge + Tax
RateTypeCode Y The code for the rate type. Will be one of the following options:
F: Flat rate
H: Hourly
E: Estimated amount
N: Currently not available
CategoryCode N Extra information that will be passed back during sell request to help identify the rate.
Currency Y The 3-letter ISO 4217 currency code for the rate amount.
NoRateText N Explanation of rate type. Provided if RateTypeCode = N
MinHours N The minimum number of hours for the reservation.
DiscountType N The type of discount applied.
BasePrice N The reservation price without taxes, surcharges or service charges.
ServiceCharge N The service charge for the reservation.
SurCharge N This element contains the desc attribute, with text describing the reason for the surcharge. Example: <SurCharge desc="fuel">
Tax N The reservation tax.
ExtraPickupCharge N Any additional fees for the pickup service.
ExtraDropoffCharge N Any additional fees for the drop off service.
OptionalExtraStopCharge N The charge for any additional stops.
OptionalExtraTimeCharge N The charge for each additional hour.

Vehicle Elements

Element Description
VehicleType One of the following values:
100: Sedan
200: Limo
250: Stretch Limo
300: SUV
350: Stretch SUV
400: Van
450: Mini-Bus
500: Motor Coach
600: Shuttle
700: Trolley
800: Carriage
900: Any
VehicleID Information to identify the specific vehicle.

Vendor Elements

Element Description
VendorCode The vendor code for the vendor.
VendorName The vendor's name.
PhoneNumber The vendor's phone number.

FormOfPayment Elements

Element Description
CreditCard If present, the passenger will pay with credit card. Refer to the Reply Credit Card elements table for the child elements.
Cash If present, the passenger will pay cash.
Check If present, the passenger will pay with a check.
DirectBilling If present, the passenger will pay through direct billing.

Post a reservation - Reply Credit Card Elements

Element Name Required? Description
Type Y The card type.
Number Y The card number.
Expiration Y The card expiration date. Format: 2013-02-19

Post A Reservation Sell Request - XML Example of Successful Response

HTTPS/1.1 200 OK
Content-Type: application/xml
Content-Length: {length of content body}

<CC_LimoSellReply>
  <Error>
      <ErrorCode />
      <ErrorSource />
      <ErrorDescription />
  </Error>
  <ReservationID>1234</ReservationID>
  <Status>RB</Status>
  <ConfNum>4444</ConfNum>
  <CancelPolicy />
  <CancelNum>55555</CancelNum>
  <PrimaryPassenger>
      <FirstName>Chris</FirstName>
      <LastName>Miller</LastName>
      <Phone>5551234567</Phone>
      <Phone2>5551234568</Phone2>
      <CellPhone>5551234569</CellPhone>
      <EmailAddress>cmiller@example.com</EmailAddress>
  </PrimaryPassenger>
  <ServiceType>110</ServiceType>
  <ClassOfService />
  <PickupLocation>
      <LocationType>100</LocationType>
      <Airport>
          <AirportCode />
          <Flight>
              <CarrierCode />
              <FlightNumber />
              <ArrivalDateTime />
          </Flight>
      </Airport>
      <TrainStation>
          <StationCode />
          <StationName />
          <City />
          <State />
          <Train>
              <CarrierCode />
              <CarrierName />
              <TrainNumber />
              <ArrivalDateTime />
          </Train>
      </TrainStation>
      <Address>209 Madison St</Address>
      <City>Alexandria</City>
      <State>VA</State>
      <Country>US</Country>
      <PostalCode>22314</PostalCode>
      <ExtraNotes />
  </PickupLocation>
  <DropoffLocation>
      <LocationType>200</LocationType>
      <Airport>
          <AirportCode>DCA</AirportCode>
          <Flight>
              <CarrierCode>UA</CarrierCode>
              <FlightNumber>333</FlightNumber>
              <DepartureDateTime>2012-02-19T11:29:00</DepartureDateTime>
          </Flight>
      </Airport>
      <TrainStation>
          <StationCode />
          <StationName />
          <City />
          <State />
          <Train>
              <CarrierCode />
              <CarrierName />
              <TrainNumber />
              <DepartureDateTime />
          </Train>
      </TrainStation>
      <Address />
      <City />
      <State />
      <Country />
      <PostalCode />
      <ExtraNotes />
  </DropoffLocation>
  <StartDateTime>2012-02-19T09:00:00</StartDateTime>
  <EndDateTime />
  <PickupInstructions>pick me up</PickupInstructions>
  <DropoffInstructions>None</DropoffInstructions>
  <LanguageCode>en-us</LanguageCode>
  <Currency>USD</Currency>
  <NumPassengers>1</NumPassengers>
  <RequestedDriver />
  <SpecialServiceRequest />
  <PickupServiceArrangement />
  <DropoffServiceArrangement />
  <ExtraStopArrangement />
  <RateInfo>
      <RateID>5</RateID>
      <Rate>42.50</Rate>
      <RateTypeCode>E</RateTypeCode>
      <CategoryCode />
      <MinHours />
      <Currency>US</Currency>
      <NoRateText />
      <DiscountType />
      <BasePrice>35.00</BasePrice>
      <ServiceCharge>5.00</ServiceCharge>
      <SurCharge desc="fuel">1.00</SurCharge>
      <Tax>1.50</Tax>
      <ExtraPickupCharge />
      <ExtraDropoffCharge />
      <OptionalExtraStopCharge />
      <OptionalExtraTimeCharge />
      <Message />
  </RateInfo>
  <RateDisclaimer />
  <Vehicle>
      <VehicleType>100</VehicleType>
      <Description>This is a Sedan.</Description>
      <MaxPassengers>1</MaxPassengers>
      <VehicleID>12</VehicleID>
  </Vehicle>
  <Vendor>
      <VendorCode>LML</VendorCode>
      <VendorName>LimoVendor</VendorName>
      <PhoneNumber>4354654654</PhoneNumber>
  </Vendor>
  <ProviderFeedback />
  <FormOfPayment>
      <Cash />
      <Check />
      <DirectBilling />
      <CreditCard>
          <Type>VI</Type>
          <Number>XXXXXXXXXXXX1111</Number>
          <Expiration>2013-02-19</Expiration>
      </CreditCard>
  </FormOfPayment>
  <AccountingInfo>
      <AccountingField1>715</AccountingField1>
      <AccountingField2>temp@outtask.com</AccountingField2>
      <AccountingField3>11</AccountingField3>
      <AccountingField4>Development</AccountingField4>
      <AccountingField5/>
  </AccountingInfo>
</CC_LimoSellReply>

Post a transportation search

A post transportation search request is sent when the Travel user searches for ground transportation.

Post a transportation search - Request

URI

The Ground Transportation direct connect sends the relevant information to a URI that the travel supplier maintains. The standard location is:

https://{servername}/concur/groundtransportation

The URI is configured by the supplier when registering the partner application.

Headers

Accept Header

application/xml

Authorization Header

Authorization header with OAuth credentials.

Post a transportation search - Request Body

The request will contain a CC_LimoSearchRequest parent element, containing the following child elements.

ServiceType: The type of service requested. Will contain one of the following values:

100: Point to point
110: One way to airport
111: One way from airport
120: One way to train station
121: One way from train station
200: Hourly
300: Airport to airport

ClassOfService: The requested service class. Will contain one of the following values:

100: Normal
200: High
300: Highest

If this value is not provided by the user, it will default to 100.

PickupLocation: The pick up location. This parent element contains the following child elements:

Post a transportation search - PickupLocation Elements

Element Description
LocationType One of the following: 100 - Address, 200 - Airport, 300 - Train station.
Airport Refer to the Airport Elements table. Provided if the LocationType = 200.
TrainStation Refer to the Train Station Elements table. Provided if the LocationType = 300.
Address The street address of the location. Provided if the LocationType = 100.
City The location city.
State The location state. Preferably 2 characters, max 10 characters.
Country The location's 2 character ISO 3166-1 alpha-2 country code. Example: US
PostalCode The location postal code.
ExtraNotes Additional notes about the location. Example: Ring doorbell, Holiday Inn, etc.

DropoffLocation: The drop off location. This parent element contains the following child elements:

Post a transportation search - DropoffLocation Elements

Element Description
LocationType One of the following: 100 - Address, 200 - Airport, 300 - Train station.
Airport Refer to the Airport Elements table. Provided if the LocationType = 200.
TrainStation Refer to the Train Station Elements table. Provided if the LocationType = 300.
Address The street address of the location. Provided if the LocationType = 100.
City The location city.
State The location state. Preferably 2 characters, max 10 characters.
Country The location's 2 character ISO 3166-1 alpha-2 country code. Example: US
PostalCode The location postal code.
ExtraNotes Additional notes about the location. Example: Apartment building, gravel driveway, etc.

StartDateTime: The time, in GMT, that the reservation must begin. Format: 2015-05-19T18:00:00

EndDateTime: The time, in GMT that the reservation will end. Provided for hourly reservations. Format: 2015-05-19T18:00:00

PickupInstructions: Additional instructions about the pick up request.

DropoffInstructions: Additional instructions about the drop off request.

LanguageCode: The language of the traveler. Will be one of the following options:

en: English
en-us: English (US)
en-gb: English (UK)
fr: French
fr-ca: French (Canadian)
de: German
pt: Portuguese
es: Spanish
nl: Dutch
it: Italian
ja: Japanese
pl: Polish
pt-br: Portuguese (Brazilian)
ru: Russian
hu: Hungarian
ko: Korean
sv: Swedish
zh-cn: Chinese
zh-tw: Traditional Chinese

Currency: The 3-letter ISO 4217 currency code for the reservation amount.

NumPassengers: The number of passengers.

VehicleType: The type of vehicle requested. Will be one of the following options:

100: Sedan
200: Limo
201: Stretch Limo
300: SUV
301: Stretch SUV
400: Van
401: Mini-Bus
402: Bus
500: Motor Coach
501: Antique/Classic
502: Trolley
503: Carriage
600: Shuttle
900: Any

DiscountCode: The discount code information. This parent element contains the following child elements:

post-a-transportation-search - DiscountCode Elements

Element Description
CorporateID The user's corporate ID.
VendorCode The user's vendor code.
DiscountNumber The user's discount number.

Post a transportation search - Airport Elements

AirportCode: The IATA Code for the airport.

Flight: The flight information. This parent element contains the following child elements:

Post a transportation search - Flight Elements

Element Description
CarrierCode The airline code.
FlightNumber The flight number.
ArrivalDateTime The flight arrival time. Only provided for the PickupLocation element. Format: 2015-05-19T18:00:00
DepartureDateTime The flight departure time. Only provided for the DropoffLocation element. Format: 2015-05-19T18:00:00

Post a transportation search - Train Station Elements

Element Description
StationCode The station code.
StationName The name of the station.
City The city the station is located in.
State The state the station is located in. Preferably 2 characters, max 10 characters.
Train The train information. This parent element contains the following child elements.

Post a transportation search - Train Elements

Element Description
CarrierCode The code of the train carrier.
CarrierName The name of the train carrier.
TrainNumber The train number.
ArrivalDateTime The train arrival time. Only provided for the PickupLocation element. Format: 2015-05-19T18:00:00
DepartureDateTime The train departure time. Only provided for the DropoffLocation element. Format: 2015-05-19T18:00:00

Post a transportation search - Response

The supplier responds to the Limo Search request by returning the details of an available reservation that matches the search criteria.

Content Types

application/xml

Post a transportation search - Content Body

The response will include a CC_LimoSearchReply parent element, with the following child elements:

Error: The error information, if an error occurred. Required. This parent element contains the following child elements:

Post a transportation searh - Error Elements

Element Description
ErrorCode The code for the error. Will contain one of the following values:
100: Pickup/dropoff location related error
200: Pickup/dropoff time related error
300: Other request parameters related error
400: Credential related error
500: No rate/service available
900: Unknown error
ErrorSource The source of the error.
ErrorDescription The additional error information.

RequestData: This parent element contains a copy of the original request data. Only the ServiceType, PickupLocation, DropoffLocation, and StartDateTime elements are required.

Limos: This parent element contains a Limo child element with the available reservation information. Refer to the Limo Elements table for the details of the child elements of the Limo element.

Post a transportation search - Limo Elements

RateInfo: The rate information for the limo. Refer to the Rate Information Elements table for more information. Required.

Vehicle: The type of vehicle. Required. This parent element contains the following child elements:

VehicleType: One of the following values:

100: Sedan
200: Limo
250: Stretch Limo
300: SUV
350: Stretch SUV
400: Van
450: Mini-Bus
500: Motor Coach
600: Shuttle
700: Trolley
800: Carriage
900: Any

Description: The detailed description of the vehicle.

MaxPassengers: The maximum number of passengers allowed in the vehicle. Must be greater than zero.

VehicleID: Information to identify the specific vehicle.

Vendor: The reservation vendor. Required. This parent element contains the following child elements:

Post a transportation search - Vendor Elements

Element Description
VendorCode The vendor code for the vendor.
VendorName The vendor's name.
PhoneNumber The vendor's phone number.

AcceptedFops: The accepted forms of payment. Required. This parent element contains the FormOfPayment child element. The FormOfPayment element contains the allowed forms of payment. The possible child elements are:

Post a transportation search - FormOfPayment Elements

Element Description
CreditCard This element will appear if the Credit Card form of payment is accepted. Contains the Type child element with one of the following values: AX - American Express, CA - Master Card, VI - Visa, DS - Discover Card, DC - Diners Club
Cash This element will appear if the Cash form of payment is accepted.
Check This element will appear if the Check form of payment is accepted.
DirectBilling This element will appear if the Direct Billing form of payment is accepted.

Post a transportation search - Rate Information Elements

Element Required? Description
RateID Y The rate identifier.
Rate Y The BasePrice + ServiceCharge + SurCharge + Tax
RateTypeCode Y The code for the rate type. Will be one of the following options:
F: Flat rate
H: Hourly
E: Estimated amount
N: Currently not available
CategoryCode N Extra information that will be passed back during sell request to help identify the rate.
Currency Y The 3-letter ISO 4217 currency code for the rate amount.
NoRateText N Explanation of rate type. Provided if RateTypeCode = N
MinHours N The minimum number of hours for the reservation.
DiscountType N The type of discount applied.
BasePrice N The reservation price without taxes, surcharges or service charges.
ServiceCharge N The service charge for the reservation.
SurCharge N This element contains the desc attribute, with text describing the reason for the surcharge. Example: <SurCharge desc="fuel">
Tax N The reservation tax.
ExtraPickupCharge N Any additional fees for the pickup service.
ExtraDropoffCharge N Any additional fees for the drop off service.
OptionalExtraStopCharge N The charge for any additional stops.
OptionalExtraTimeCharge N The charge for each additional hour.

Post a transportation search - Examples

XML Example Request

POST /concur/groundtransportation HTTPS/1.1
Host: example.com
Authorization: Basic ...
Content-Type: application/xml
Content-Length: {length of content body}

<CC_LimoSearchRequest>
    <ServiceType>110</ServiceType>
    <ClassOfService>100</ClassOfService>
    <PickupLocation>
        <LocationType>100</LocationType>
        <Airport>
            <AirportCode />
        </Airport>
        <Address>209 Madison St., Suite 400</Address>
        <City>Alexandria</City>
        <State>VA</State>
        <Country>US</Country>
        <PostalCode>22314</PostalCode>
    </PickupLocation>
    <DropoffLocation>
        <LocationType>200</LocationType>
        <Airport>
            <AirportCode>DCA</AirportCode>
        </Airport>
        <Address />
        <City />
        <State />
        <Country />
        <PostalCode />
    </DropoffLocation>
    <StartDateTime>2012-03-14T09:00</StartDateTime>
    <EndDateTime />
    <PickupInstructions />
    <DropoffInstructions />
    <LanguageCode>en-us</LanguageCode>
    <Currency>USD</Currency>
    <NumPassengers>1</NumPassengers>
    <DiscountCode />
    <VehicleType>100</VehicleType>
</CC_LimoSearchRequest>

XML Example of Successful Response

HTTPS/1.1 200 OK
Content-Type: application/xml
Content-Length: {length of content body}

<CC_LimoSearchReply size="1396" elaspedMs="782">
    <Error>
        <ErrorCode />
        <ErrorSource />
        <ErrorDescription />
    </Error>
    <RequestData>
        <ServiceType>110</ServiceType>
        <ClassOfService>100</ClassOfService>
        <PickupLocation>
            <Airport />
            <Address>209 Madison St. #400</Address>
            <City>Alexandria</City>
            <State>VA</State>
            <Country>US</Country>
            <PostalCode>22314</PostalCode>
        </PickupLocation>
        <DropoffLocation>
            <Airport>DCA</Airport>
            <Address />
            <City />
            <State />
            <Country />
            <PostalCode />
        </DropoffLocation>
        <StartDateTime>2012-02-19T09:00:00</StartDateTime>
        <EndDateTime />
        <PickupInstructions />
        <DropoffInstructions />
        <Country>US</Country>
        <NumPassengers>1</NumPassengers>
        <VehicleType>100</VehicleType>
    </RequestData>
    <Limos>
        <Limo>
            <RateInfo>
                <RateID>1</RateID>
                <Rate>42.50</Rate>
                <RateTypeCode>100</RateTypeCode>
                <CategoryCode />
                <MinHours />
                <Currency>USD</Currency>
                <NoRateText />
                <DiscountType />
                <BasePrice>35.00</BasePrice>
                <ServiceCharge>5.00</ServiceCharge>
                <SurChange desc="fuel">1.00</SurChange>
                <Tax>1.50</Tax>
                <ExtraPickupCharge />
                <ExtraDropoffCharge />
                <OptionalExtraStopCharge />
                <OptionalExtraTimeCharge />
                <Message>Ordinary Limo</Message>
            </RateInfo>
            <Vehicle>
                <VehicleType>Sedan</VehicleType>
                <Description>This is a Sedan.</Description>
                <MaxPassengers>1</MaxPassengers>
                <VehicleID>12</VehicleID>
            </Vehicle>
            <Vendor>
                <VendorCode>LML</VendorCode>
                <VendorName>LimoVendor</VendorName>
                <PhoneNumber>4354654654</PhoneNumber>
            </Vendor>
            <AcceptedFops>
                <FormOfPayment>
                    <CreditCard>
                        <Type>VI</Type>
                    </CreditCard>
                </FormOfPayment>
            </AcceptedFops>
        </Limo>
    </Limos>
</CC_LimoSearchReply>

Update reservation with supplier

This request is sent when the Travel user updates an existing ground transportation reservation.

Update Reservation With Supplier - Request

URI

The Ground Transportation direct connect sends the relevant information to a URI that the travel supplier maintains. The standard location is:

https://{servername}/concur/groundtransportation

The URI is configured by the supplier when registering the partner application.

Headers

Accept Header

application/xml

Authorization Header

Authentication header with Base64 encoded basic authentication credentials (login ID and password) is required. The basic authentication credentials are established during the application review process.

Authorization: Basic {Base64 encoded LoginID:Password}

Update Reservation With Supplier - Request Body

The request will contain a CC_LimoUpdateRequest parent element, containing the following child elements:

Element Required? Description
ReservationID The unique identifier for the reservation.
CorporateClient The corporate client the booking is on behalf of. This parent element contains a CompanyCode child element containing the code for the company of the client.
Booker The user booking the reservation. For information about the child elements of this parent element, see the Booker elements table below.
PrimaryPassenger The passenger contact name for the reservation. For information about the child elements of this parent element, see the PrimaryPassenger elements table below.
ServiceType The type of service requested. Will contain one of the following values:
100: Point to point
110: One way to airport
111: One way from airport
120: One way to train station
121: One way from train station
200: Hourly
300: Airport to airport
ClassOfService The requested service class. Will contain one of the following values:
100: Normal
200: High
300: Highest

If this value is not provided by the user, it will default to 100.
PickupLocation The pick up location. For information about the child elements of this parent element, see the PickupLocation elements table below.
DropoffLocation The drop off location. For information about the child elements of this parent element, see the DropoffLocation elements table below.
StartDateTime The time, in GMT, that the reservation must begin. Format: 2015-05-19T18:00:00
EndDateTime The time, in GMT that the reservation will end. Provided for hourly reservations. Format: 2015-05-19T18:00:00
PickupInstructions Additional instructions about the pick up request.
DropoffInstructions Additional instructions about the drop off request.
LanguageCode The language of the traveler. Will be one of the following options:
en: English
en-us: English (US)
en-gb: English (UK)
fr: French
fr-ca: French (Canadian)
de: German
pt: Portuguese
es: Spanish
nl: Dutch
it: Italian
ja: Japanese
pl: Polish
pt-br: Portuguese (Brazilian)
ru: Russian
hu: Hungarian
ko: Korean
sv: Swedish
zh-cn: Chinese
zh-tw: Traditional Chinese
Currency The 3-letter ISO 4217 currency code for the reservation amount.
NumPassengers The number of passengers.
DiscountCode The discount code information. For information about the child elements of this parent element, see the DiscountCode elements table below.
FormOfPayment The form of payment for the reservation. For information about the child elements of this parent element, see the FormOfPayment elements table below.
AccountingInfo The accounting information for the reservation. This parent element contains one or more AccountingField elements: AccountingField1 through AccountingField5. These fields contain detailed accounting information.
RequestedDriver The name of the requested driver, if available.
SpecialServiceRequest The details of the special service request, if available.
PickupServiceArrangement The details of the pickup arrangement, if available.
DropoffServiceArrangement The details of the dropoff arrangement, if available.
ExtraStopArrangement The details of the extra stop arrangement, if available.

Update Reservation With Supplier - Booker Elements

Element Description
UserID The user's SAP Concur user ID.
EmailAddress The user's email address.
Phone The user's contact number.

Update Reservation With Supplier - PrimaryPassenger Elements

Element Description
FirstName The contact's first name.
LastName The contact's last name.
Phone The contact's phone number.
Phone2 The contact's backup phone number.
CellPhone The contact's cell phone number.
EmailAddress The contact's email address.

Update Reservation With Supplier - PickupLocation Elements

Element Description
LocationType One of the following: 100 - Address, 200 - Airport, 300 - Train station.
Airport Refer to the Airport elements table. Provided if the LocationType = 200.
TrainStation Refer to the Train Station elements table. Provided if the LocationType = 300.
Address The street address of the location. Provided if the LocationType = 100.
City The location city.
State The location state. Preferably 2 characters, max 10 characters.
Country The location's 2 character ISO 3166-1 alpha-2 country code. Example: US
PostalCode The location postal code.
ExtraNotes Additional notes about the location. Example: Ring doorbell, Holiday Inn, etc.

Update Reservation With Supplier - DropoffLocation Elements

Element Description
LocationType One of the following: 100 - Address, 200 - Airport, 300 - Train station, 400 - As directed.
Airport Refer to the Airport elements table. Provided if the LocationType = 200.
TrainStation Refer to the Train Station elements table. Provided if the LocationType = 300.
Address The street address of the location. Provided if the LocationType = 100.
City The location city.
State The location state. Preferably 2 characters, max 10 characters.
Country The location's 2 character ISO 3166-1 alpha-2 country code. Example: US
PostalCode The location postal code.
ExtraNotes Additional notes about the location. Example: Apartment Building, gravel driveway, etc.

Update Reservation With Supplier - DiscountCode Elements

Element Name Description
CorporateID The user's corporate ID.
VendorCode The user's vendor code.
DiscountNumber The user's discount number.

FormOfPayment Elements

Element Description
CreditCard If present, the passenger will pay with credit card. Refer to the Credit Card Elements table for the child elements.
Cash If present, the passenger will pay cash.
Check If present, the passenger will pay with a check.
DirectBilling If present, the passenger will pay through direct billing.

Airport Elements

Element Name Description
AirportCode The IATA code for the airport.
Flight The flight information. For information about the child elements of this parent element, see the Flight elements table below.

Flight Elements

Element Name Description
CarrierCode The airline code.
FlightNumber The flight number.
ArrivalDateTime The flight arrival time. Only provided for the PickupLocation element. Format: 2015-05-19T18:00:00
DepartureDateTime The flight departure time. Only provided for the DropoffLocation element. Format: 2015-05-19T18:00:00

Train Station Elements

Element Name Required/Optional Data Type Description
StationCode The station code.
StationName The name of the station.
City The city the station is located in.
State The state the station is located in. Preferably 2 characters, max 10 characters.
Train The train information. For information about the child elements of this parent element, see the Train elements table below.

Train Elements

Element Name Description
CarrierCode The code of the train carrier.
CarrierName The name of the train carrier.
TrainNumber The train number.
ArrivalDateTime The train arrival time. Only provided for the PickupLocation element. Format: 2015-05-19T18:00:00
DepartureDateTime The train departure time. Only provided for the DropoffLocation element. Format: 2015-05-19T18:00:00

Update Reservation With Supplier - Credit Card Elements

Element Name Description
Type The card type.
Number The card number.
Expiration The card expiration date. Format: 2013-02-19
Name The name on the card.
Address The street information of the billing address of the car.
City The city of the billing address of the car.
State The state of the billing address of the car.
Country The country of the billing address of the car.
PostalCode The postal code of the billing address of the car.

Update Reservation With Supplier - Response

The supplier responds to the update request with the reservation details.

Content Types

application/xml

Update Reservation With Supplier - Response Schema

The response will include a CC_LimoUpdateReply parent element, with the following child elements:

Element Required? Description
Error Y The error information, if an error occurred. For information about the child elements of this parent element, see the Error elements table below.
ReservationID N The identifier for the reservation.
Status N The status of the reservation. The value will be one of the following:
RB: Reservation Booked
RA: Reservation Accepted
RD: Reservation Declined
CB: Change Booked
CA: Change Accepted
CD: Change Declined
XB: Cancellation Requested
XA: Cancellation Accepted
XD: Cancellation Declined
RC: Reservation Closed
ConfNum N The confirmation number for the reservation.
CancelPolicy N The cancellation policy for the reservation.
CancelNum N The cancellation number for the reservation.
PrimaryPassenger Y The passenger contact name for the reservation. For information about the child elements of this parent element, see the PrimaryPassenger elements table above.
ServiceType Y The type of service requested. Will contain one of the following values:
100: Point to point
110: One way to airport
111: One way from airport
120: One way to train station
121: One way from train station
200: Hourly
300: Airport to airport
ClassOfService N The requested service class. Will contain one of the following values:
100: Normal
200: High
300: Highest

If this value is not provided by the user, it will default to 100.
PickupLocation Y The pick up location. For information about the child elements of this parent element, see the PickupLocation elements table above.
DropoffLocation Y The drop off location. For information about the child elements of this parent element, see the DropoffLocation elements table above.
StartDateTime Y The time, in GMT, that the reservation must begin. Format: 2015-05-19T18:00:00
EndDateTime N The time, in GMT that the reservation will end. Provided for hourly reservations. Format: 2015-05-19T18:00:00
PickupInstructions N Additional instructions about the pick up request.
DropoffInstructions N Additional instructions about the drop off request.
LanguageCode Y The language of the traveler. Will be one of the following options:
en: English
en-us: English (US)
en-gb: English (UK)
fr: French
fr-ca: French (Canadian)
de: German
pt: Portuguese
es: Spanish
nl: Dutch
it: Italian
ja: Japanese
pl: Polish
pt-br: Portuguese (Brazilian)
ru: Russian
hu: Hungarian
ko: Korean
sv: Swedish
zh-cn: Chinese
zh-tw: Traditional Chinese
Currency Y The 3-letter ISO 4217 currency code for the reservation amount.
NumPassengers N The number of passengers.
RequestedDriver N The name of the requested driver, if available.
SpecialServiceRequest N The details of the special service request, if available.
PickupServiceArrangement N The details of the pickup arrangement, if available.
DropoffServiceArrangement N The details of the dropoff arrangement, if available.
ExtraStopArrangement N The details of the extra stop arrangement, if available.
RateInfo Y The booked rate details. Refer to the Rate Information elements table below for more information.
Vehicle Y The vehicle details. For information about the child elements of this parent element, see the Vehicle elements table below.
Vendor Y The reservation vendor. For information about the child elements of this parent element, see the Vendor elements table below.
FormOfPayment Y The form of payment for the reservation. For information about the child elements of this parent element, see the FormOfPayment elements table below.
RateDisclaimer N Disclaimer text about the rate.
ProviderFeedback N Any additional feedback from the supplier.
AccountingInfo N The accounting information for the reservation. This parent element contains one or more AccountingField elements: AccountingField1 through AccountingField5. These fields contain detailed accounting information.

Update Reservation With Supplier - Error Elements

Element Description
ErrorCode The code for the error. Will contain one of the following values:
100: Pickup/dropoff location related error
200: Pickup/dropoff time related error
300: Other request parameters related error
400: Credential related error
500: No rate/service available
600: FOP related error
900: Unknown error
ErrorSource The source of the error.
ErrorDescription The additional error information.

Update Reservation With Supplier - Vehicle Elements

Element Description
VehicleType One of the following values:
100: Sedan
200: Limo
250: Stretch Limo
300: SUV
350: Stretch SUV
400: Van
450: Mini-Bus
500: Motor Coach
600: Shuttle
700: Trolley
800: Carriage
900: Any
Description The vehicle description.
MaxPassengers The maximum number of passengers for the car. Must be greater than zero.
VehicleID Information to identify the specific vehicle.

Update Reservation With Supplier - Rate Information Elements

Element Name Required? Data Type Description
RateID Y The rate identifier.
Rate Y The BasePrice + ServiceCharge + SurCharge + Tax
RateTypeCode Y The code for the rate type. Will be one of the following options:
F: Flat rate
H: Hourly
E: Estimated amount
N: Currently not available
CategoryCode N Extra information that will be passed back during sell request to help identify the rate.
Currency Y The 3-letter ISO 4217 currency code for the rate amount.
NoRateText N Explanation of rate type. Provided if RateTypeCode = N
MinHours N The minimum number of hours for the reservation.
DiscountType N The type of discount applied.
BasePrice N The reservation price without taxes, surcharges or service charges.
ServiceCharge N The service charge for the reservation.
SurCharge N This element contains the desc attribute, with text describing the reason for the surcharge. Example: <SurCharge desc="fuel">
Tax N The reservation tax.
ExtraPickupCharge N Any additional fees for the pickup service.
ExtraDropoffCharge N Any additional fees for the drop off service.
OptionalExtraStopCharge N The charge for any additional stops.
OptionalExtraTimeCharge N The charge for each additional hour.

Update Reservation With Supplier - Vendor Elements

Element Description
VendorCode The vendor code for the vendor.
VendorName The vendor's name.
PhoneNumber The vendor's phone number.

FormOfPayment Elements

Element Description
CreditCard If present, the passenger will pay with credit card. Refer to the Reply Credit Card elements table for the child elements.
Cash If present, the passenger will pay cash.
Check If present, the passenger will pay with a check.
DirectBilling If present, the passenger will pay through direct billing.

Airport Elements

Element Name Description
AirportCode The IATA code for the airport.
Flight The flight information. For information about the child elements of this parent element, see the Flight elements table below.

Flight Elements

Element Name Description
CarrierCode The airline code.
FlightNumber The flight number.
ArrivalDateTime The flight arrival time. Only provided for the PickupLocation element. Format: 2015-05-19T18:00:00
DepartureDateTime The flight departure time. Only provided for the DropoffLocation element. Format: 2015-05-19T18:00:00

Train Station Elements

Element Name Required/Optional Data Type Description
StationCode The station code.
StationName The name of the station.
City The city the station is located in.
State The state the station is located in. Preferably 2 characters, max 10 characters.
Train The train information. For information about the child elements of this parent element, see the Train elements table below.

Train Elements

Element Name Description
CarrierCode The code of the train carrier.
CarrierName The name of the train carrier.
TrainNumber The train number.
ArrivalDateTime The train arrival time. Only provided for the PickupLocation element. Format: 2015-05-19T18:00:00
DepartureDateTime The train departure time. Only provided for the DropoffLocation element. Format: 2015-05-19T18:00:00

Update Reservation With Supplier - Reply Credit Card Elements

Element Name Required? Description
Type The card type.
Number The card number.
Expiration The card expiration date. Format: 2013-02-19

Examples

XML Example Request

POST /concur/groundtransportation HTTPS/1.1
Host: example.com
Authorization: Basic ...
Content-Type: application/xml
Content-Length: {length of content body}

<CC_LimoUpdateRequest>
    <ReservationID>1234</ReservationID>
    <CorporateClient>
        <CompanyCode>339</CompanyCode>
    </CorporateClient>
    <Booker>
        <UserID>55414</UserID>
        <EmailAddress>cmiller@example.com</EmailAddress>
        <Phone>5551234567</Phone>
    </Booker>
    <PrimaryPassenger>
        <FirstName>Chris</FirstName>
        <LastName>Miller</LastName>
        <Phone>5551234567</Phone>
        <Phone2>5551234568</Phone2>
        <CellPhone>5551234555</CellPhone>
        <EmailAddress>cmiller@example.com</EmailAddress>
    </PrimaryPassenger>
    <ServiceType>110</ServiceType>
    <ClassOfService />
    <PickupLocation>
        <LocationType>100</LocationType>
        <Airport>
            <AirportCode />
            <Flight>
                <CarrierCode />
                <FlightNumber />
                <ArrivalDateTime />
            </Flight>
        </Airport>
        <TrainStation>
            <StationCode />
            <StationName />
            <City />
            <State />
            <Train>
                <CarrierCode />
                <CarrierName />
                <TrainNumber />
                <ArrivalDateTime />
            </Train>
        </TrainStation>
        <Address>209 Madison St</Address>
        <City>Alexandria</City>
        <State>VA</State>
        <Country>US</Country>
        <PostalCode>22314</PostalCode>
        <ExtraNotes />
    </PickupLocation>
    <DropoffLocation>
        <LocationType>200</LocationType>
        <Airport>
            <AirportCode>DCA</AirportCode>
            <Flight>
                <CarrierCode>UA</CarrierCode>
                <FlightNumber>333</FlightNumber>
                <DepartureDateTime>2012-02-19T11:29:00</DepartureDateTime>
            </Flight>
        </Airport>
        <TrainStation>
            <StationCode />
            <StationName />
            <City />
            <State />
            <Train>
                <CarrierCode />
                <CarrierName />
                <TrainNumber />
                <DepartureDateTime />
            </Train>
        </TrainStation>
        <Address />
        <City />
        <State />
        <Country />
        <PostalCode />
        <ExtraNotes />
    </DropoffLocation>
    <StartDateTime>2012-02-19T09:00:00</StartDateTime>
    <EndDateTime />
    <PickupInstructions>pick me up</PickupInstructions>
    <DropoffInstructions>None</DropoffInstructions>
    <LanguageCode>en-us</LanguageCode>
    <Currency>USD</Currency>
    <NumPassengers>1</NumPassengers>
    <DiscountCode>
        <CorporateID />
        <VendorCode />
        <DiscountNumber />
    </DiscountCode>
    <FormOfPayment>
        <Cash />
        <Check />
        <DirectBilling />
        <CreditCard>
            <Type>VI</Type>
            <Number>XXXXXXXXXXXX1111</Number>
            <Expiration>2013-02-19</Expiration>
        </CreditCard>
    </FormOfPayment>
    <AccountingInfo>
        <AccountingField1>715</AccountingField1>
        <AccountingField2>temp@outtask.com</AccountingField2>
        <AccountingField3>11</AccountingField3>
        <AccountingField4>Development</AccountingField4>
        <AccountingField5/>
    </AccountingInfo>
    <RequestedDriver />
    <SpecialServiceRequest />
    <PickupServiceArrangement />
    <DropoffServiceArrangement />
    <ExtraStopArrangement />
</CC_LimoUpdateRequest>

XML Example of Successful Response

HTTPS/1.1 200 OK
Content-Type: application/xml
Content-Length: {length of content body}

<CC_LimoUpdateReply>
    <Error>
        <ErrorCode />
        <ErrorSource />
        <ErrorDescription />
    </Error>
    <ReservationID>1234</ReservationID>
    <Status>RB</Status>
    <ConfNum/>
    <CancelPolicy />
    <CancelNum/>
    <PrimaryPassenger>
        <FirstName>Chris</FirstName>
        <LastName>Miller</LastName>
        <Phone>5551234567</Phone>
        <Phone2>5551234568</Phone2>
        <CellPhone>5551234555</CellPhone>
        <EmailAddress>cmiller@example.com</EmailAddress>
    </PrimaryPassenger>
    <ServiceType>110</ServiceType>
    <ClassOfService />
    <PickupLocation>
        <LocationType>100</LocationType>
        <Airport>
            <AirportCode />
            <Flight>
                <CarrierCode />
                <FlightNumber />
                <ArrivalDateTime />
            </Flight>
        </Airport>
        <TrainStation>
            <StationCode />
            <StationName />
            <City />
            <State />
            <Train>
                <CarrierCode />
                <CarrierName />
                <TrainNumber />
            </Train>
        </TrainStation>
        <Address>209 Madison St #400</Address>
        <City>Alexandria</City>
        <State>VA</State>
        <Country>US</Country>
        <PostalCode>22314</PostalCode>
        <ExtraNotes />
    </PickupLocation>
    <DropoffLocation>
        <LocationType>200</LocationType>
        <Airport>
            <AirportCode>DCA</AirportCode>
            <Flight>
                <CarrierCode>UA</CarrierCode>
                <FlightNumber>333</FlightNumber>
                <DepartureDateTime>2012-02-19T11:29:00</DepartureDateTime>
            </Flight>
        </Airport>
        <TrainStation>
            <StationCode />
            <StationName />
            <City />
            <State />
            <Train>
                <CarrierCode />
                <CarrierName />
                <TrainNumber />
                <DepartureDateTime />
            </Train>
        </TrainStation>
        <Address />
        <City />
        <State />
        <Country />
        <PostalCode />
        <ExtraNotes />
    </DropoffLocation>
    <StartDateTime>2012-02-19T09:00:00</StartDateTime>
    <EndDateTime />
    <PickupInstructions>pick me up</PickupInstructions>
    <DropoffInstructions>None</DropoffInstructions>
    <LanguageCode>en-us</LanguageCode>
    <Currency>USD</Currency>
    <NumPassengers>1</NumPassengers>
    <RequestedDriver />
    <SpecialServiceRequest />
    <PickupServiceArrangement />
    <DropoffServiceArrangement />
    <ExtraStopArrangement />
    <RateInfo>
        <RateID>5</RateID>
        <Rate>42.50</Rate>
        <RateTypeCode>E</RateTypeCode>
        <CategoryCode />
        <MinHours />
        <Currency>US</Currency>
        <NoRateText />
        <DiscountType />
        <BasePrice>35.00</BasePrice>
        <ServiceCharge>5.00</ServiceCharge>
        <SurCharge desc="fuel">1.00</SurCharge>
        <Tax>1.50</Tax>
        <ExtraPickupCharge />
        <ExtraDropoffCharge />
        <OptionalExtraStopCharge />
        <OptionalExtraTimeCharge />
        <Message />
    </RateInfo>
    <RateDisclaimer />
    <Vehicle>
        <VehicleType>100</VehicleType>
        <Description>This is a Sedan.</Description>
        <MaxPassengers>1</MaxPassengers>
        <VehicleID>12</VehicleID>
    </Vehicle>
    <Vendor>
        <VendorCode>LML</VendorCode>
        <VendorName>LimoVendor</VendorName>
        <PhoneNumber>4354654654</PhoneNumber>
    </Vendor>
    <ProviderFeedback />
    <FormOfPayment>
        <Cash />
        <Check />
        <DirectBilling />
        <CreditCard>
            <Type>VI</Type>
            <Number>XXXXXXXXXXXX1111</Number>
            <Expiration>2013-02-19</Expiration>
        </CreditCard>
    </FormOfPayment>
    <AccountingInfo>
        <AccountingField1>715</AccountingField1>
        <AccountingField2>temp@outtask.com</AccountingField2>
        <AccountingField3>11</AccountingField3>
        <AccountingField4>Development</AccountingField4>
        <AccountingField5/>
    </AccountingInfo>
</CC_LimoUpdateReply>

Direct Connect - Hotel v2

Introduction

Overview

The Hotel Services v2 Direct Connect provides a method for Travel users to access hotel inventory.

The Hotel Service 2.0 API from SAP Concur is a specification based on OTA 2015 standard for Hotel Suppliers. Please refer to XSD schema of the service and WSDL service description. This Guide provides information how the Hotel Supplier can make their content available for Concur Travel users using Hotel Service 2.0 API. Once the Hotel Supplier has developed and certified their interface with SAP Concur, their inventory will begin appearing in hotel searches by opted-in Travel users. This API has client/server architecture, where SAP Concur acts as client, pulling information from the Hotel Supplier, who acts as server, responding to SAP Concur’s requests. This guide specifies the request and response format required by SAP Concur.

This call-out differs from the in-bound SAP Concur web services in the following ways:

Contents

Introduction - Product Restrictions

Hotel Service 2 API inventory is not accessible from the SAP Concur mobile app. SAP Concur products are highly configurable, and not all clients will have access to all features.

Supported Operations

Non-Functional Requirements

Response Times

SAP Concur needs to receive all responses within 55 seconds, otherwise it causes timeout. To prevent no show fees, duplicate bookings and other similar issues, SAP Concur recommends to perform Auto-Cancel by the Hotel Supplier if ReadRQ message is not sent by SAP Concur 5 minutes after HotelResRS message was sent to SAP Concur.

Emergency Technical Contact

The Hotel supplier needs to provide emergency technical contact email that will be used for communication in case of blocking technical issues.

Testing Environment

To allow SAP Concur performing testing, the Hotel Supplier needs to provide testing URL or specify properties for testing in production URL. SAP Concur needs to be able to perform test bookings with testing credit cards.

Introduction - Security

PCI DSS Compliance

As sensitive data and payment card details are transferred via API, the Hotel Suppliers need to comply with PCI DSS standard. SAP Concur is compliant with PCI DSS standard and undergoes regular security audits.

HTTPS

SAP Concur requires TLS 1.2 (Transport Layer Security) SSL protocol for file transfers. The Hotel Supplier will provide SAP Concur HTTPS URL of its end-point. Standard HTTPS port 443 should be used.

URLs

SAP Concur will receive a single URL from the Hotel Supplier. All requests will go to that URL.

For details of all required HTTP headers refer to Headers

SAP Concur is using date as xs:date XML type "2017-05-01".

Handling of HTML

CDATA and HTML code inside of XML nodes and attributes are not allowed. These data will be escaped. The hotel suppliers should not use XML special characters - predefined entities: &, <, >, ", ' inside of ID elements like RatePlanID.

Message Structure

All messages to and from the HS2 API follow this structure:

Requests

Note: The Header element in a request must contain the Authentication element.

Responses

Note: The header in the response does not need the Authentication element.

Use Cases

Basic scenario encompassing all the functionality provided by Hotel Service 2 incorporated into Concur Travel starting from a hotel search, through to confirmation of a booking and ending with a cancellation.

Actors

  1. Primary Actor - Business traveler
  2. Secondary Actor - Hotel Supplier

Use Case

  1. Business traveler performs a search for hotels given a criteria.

  2. The UI displays the available hotels. The business traveler can then select a hotel with visible rates or request to View Rooms in case they are not present. The Business traveler selects a hotel with rates.

  3. The UI displays all available rates for the chosen hotel. The Business user can see the Cancellation Policy. The business traveler clicks on Hotel Details.

  4. The UI displays the hotel details including a long description. The Business traveler closes the Hotel Details pop-up

  5. The UI displays all available rates for the chosen hotel. The business traveler clicks on Rules and Cancellation Policy.

  6. The UI displays the Rules and the Cancellation Policy for the chosen hotel. The Business Travel closes the Rules and Cancellation Policy pop-up.

  7. The UI displays all available rates for the chosen hotel. The Business traveler selects the top most rate. The Trip Summary page is displayed where the Business traveler can set the Hotel Preferences, Enter Guest information (from their profile), select the method of payment and view the total estimated price. The Business traveler agrees to the hotel's rate rules, restrictions and cancellation policy and clicks Reserve Hotel and Continue.

  8. The UI shows the Trip Details page where the Business traveler can add items to their itinerary and review the current itinerary. The Business traveler clicks Next.

  9. The UI shows the Trip Booking Information page where the Business traveler can add trip details. The Business traveler clicks Next.

  10. The UI shows the Trip Confirmation page where the Business traveler can confirm the booking on cancel it. The Business traveler clicks Confirm Booking.

  11. The UI shows the Finished page where the Business traveler can review the trip overview and see the confirmation number along with the trip locator.

  12. The Business user can view the trip in the Upcoming Trips tab on the main Travel page. The Business traveler clicks on the Trip name.

  13. The UI shows the Trip Overview page. The Business traveler chooses the cancel the hotel reservation, by clicking cancel.

  14. The UI shows the Cancel Trip pop-up where the Business traveler may chooser to enter a comment. The Business traveler clicks OK.

  15. The UI shows the Rules and cancellation policy. The Business traveler accepts the policies by checking the 'I agree ...' button and clicking Continue

  16. The UI shows the trip cancellation page where confirmation and cancellation numbers can be found. The Business traveler closes the pop-up.

Search Criteria

Given the following example:

<RadiusDistance="5" DistanceMax="30" UnitOfMeasureCode="2">

Out of 100 returned hotels in response from the Hotel Supplier first 10 hotels are Most Preferred hotels within the 30km radius. The next 10 hotels are Preferred hotels from 30km radius. The remaining 80 hotels are hotels with no preference within the 5km radius. Note: The preference level is defined by the HotelPreference element in the TPA_Extensions, which is outlined in Search.

Reservation and Read Requests

SAP Concur will follow up a Reservation Request with a Read request as soon as possible after processing the Reservation Response. If a Read request does not arrive within 5 minutes for a given Reservation, then the supplier should treat that Reservation as an orphan and should thus seek to cancel it.

General System Overview

./media/image1.png

HTTP Headers

SAP Concur will send the user-name and password in both the HTTP header and the SOAP header. If the username and password generates an authentication error, then SAP Concur expects an HTTP 403 response.

HTTP Headers

SAP Concur will send the following HTTP headers in every request. The contents of the Authentication header will be repeated in the SOAP payload. Please note that some libraries used to handle the requests may be case sensitive.

Name Type Description
Authorization string A Base64 encoded string in the form of Basic <username:password>.
SOAPAction string The message type. The action will always be sent in lowercase. Example: search
Content-Type string All communication with the HS2 API is by way of a application/xml content type.
Accept string SAP Concur will always set the Accept header to application/xml.
Accept-Charset string SAP Concur will always set the Accept-Charset header to utf-8.
concur-correlationid string This unique code can be used during troubleshooting as it identifies the API call in the log files.
concur-traveleruuid string UUID that identifies the traveler within concur. Only sent when available.
concur-loginid string Login ID of traveler within concur. Only sent when available.

Supported Soapactions:

Soapaction Functionality
search Used to perform Search
availability Used to perform Availability
detail Used to perform Hotel Description
book Used to perform Reservation
read Used to perform Read Itinerary
cancel Used to perform Cancel

HTTP Headers - Troubleshooting

In order to assist with troubleshooting, SAP Concur provides a unique correlationId in the request header. The key to look for is correlationid. This unique code can be used during troubleshooting as it identifies the API call in the log files. You should record this information in your own API call logs as well so that you can pass this information on to the SAP Concur support team.

Example HTTP Header from network capture:

Accept: application/xml
Accept-Charset: utf-8
Authorization: *******************
concur-correlationid: A75CE5BC-90BA-4BF8-8DEA-69FA2E66E936
concur-loginid: abc@concur.com
concur-traveleruuid: <valid uuid>
Content-Type: application/xml; charset="utf-8"
SOAPAction: search
Accept-Encoding: gzip

Soap Header

The Soap header nested in the Envelope will contain an authentication element.

authentication

Name Type Description
userid string Required Contains the authentication details.
password string Required Contains the authentication details.

Sample:

<Header xmlns="http://schemas.xmlsoap.org/soap/envelope/">
  <authentication xmlns="http://www.concur.com/webservice/auth">
    <userid>testLogin123</userid>
    <password>xxxxxxxxxxxx</password>
  </authentication>
</Header>

Login and password are provided by the Hotel supplier for SAP Concur as API consumer, not per customer.

OTA Message Headers

Every message must contain the following required attributes and elements. On top of these each message may specify extra attributes and elements. Refer to a specific messages' page for details.

Request Message Headers

Name Type Description
EchoToken stringLength1to128 Required A reference for additional message identification, assigned by the requesting host system.
Version double Required The OpenTravel message version indicated by a decimal value.
PrimaryLangID string Required The primary language preference for the message encoded as ISO 639-1.
AltLangID string Required The alternate language for a customer or message encoded as ISO 639-1.
POS complex Required Point of Sale (POS) identifies the party or connection channel making the request.

POS

Name Type Description
Sources complex Required This holds the details about the requestor. Max Occurrence: 10

Source

SAP Concur will always send the ISO Currency.

Name Type Description
ISOCurrency alphaLength3 Required Currency code.
RequestorID complex An identifier of the entity making the request Examples: ATA/IATA/ID number, Electronic Reservation Service Provider (ERSP), Association of British Travel Agents (ABTA)

RequestorID

Name Type Description
Type stringLength1to32 Required Supported value: 1
ID stringLength1to32 Required The requestor ID.

Response Message Headers

The supplier is required to respond with the following attributes and elements in the root of any message. Each message may specify extra attributes and elements. Refer to a specific messages' page for details.

Name Type Description
EchoToken stringLength1to128 Required A reference for additional message identification, assigned by the requesting host system. When a request message includes an echo token the corresponding response message MUST include an echo token with an identical value.
Timestamp datetime Required Timestamp of the response operation.
Version double Required The OpenTravel message version indicated by a decimal value.
PrimaryLangID string Required The primary language preference for the message encoded as ISO 639-1.
AltLangID string Required The alternate language for a customer or message encoded as ISO 639-1.
Success / Error complex Required Indicates Success Or Error. Refer to the Error Handling page for more details.

Error Handling

SAP Concur is able to handle HTTP errors, but the preference is for the supplier to return an OTA error whenever possible. SAP Concur only ever expects one OTA error per message. Any extra errors will be ignored. Currently OTA Warnings are not supported and will be ignored.

If the error is specifically related to application level errors, please do not respond with any other error types (HTTP etc.). If you have server level issues, then it is OK to respond with HTTP standard error codes.

Errors should always be returned in a response. For example:

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <SOAP-ENV:Header xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"/>
  <soap:Body>
    <OTA_HotelSearchRS xmlns="http://www.opentravel.org/OTA/2003/05"
                       AltLangID="en"
                       EchoToken="11111111-2222-3333-4444-555555555555" PrimaryLangID="en"
                       Version="4">
      <Errors>
        <Error Code="322" ShortText="No availability" Type="13"></Error>
      </Errors>
    </OTA_HotelSearchRS>
  </soap:Body>
</soap:Envelope>

If an error is present in any message, then the content of that message is discarded and only the error element is processed. Any text from the supplier will be logged and a SAP Concur message will be displayed to the user.

Currently SAP Concur does not support displaying of supplier generated errors directly in the UI.

SAP Concur only uses the very first error that is returned, therefore any excess error elements are dropped. Any errors without a Type attribute will automatically be treated as 1 meaning Unknown. See the Error Types table below.

Name Type Description
Errors complex Element used to hold error elements. SAP Concur only expects one (1) error element. An empty errors element will be treated as an Unknown error.

Errors

Name Type Description
Error complex Element to describe a particular error. Extra text can be placed inside this element, however SAP Concur expects the error message to be sent in the ShortText attribute.

Error

Name Type Description
Type string An error type code. See the Error Types below.
ShortText string Required A description of the error. The content of this attribute will be logged, but never displayed to the user.
Code string Required An error code for a specific error.

Error Types

SAP Concur supports the following Error Type Codes in any of the responses:

Code Name Description
1 Unknown Indicates an unknown error.
2 No implementation Indicates that the target business system has no implementation for the intended request.
13 Application error Indicates that an involved back-end application returned an error which is passed back in the response message.

Note: The OTA Error-Type code of 4 - Authentication (indicates the message lacks adequate security credentials) is not expected by SAP Concur. For all authentication errors SAP Concur expects an HTTP 403.

SAP Concur expects the following errors under the given error types:

Error Type Code 1: Unknown

Error Code Description Example
188 Transaction error For errors not specified in other codes. Internal supplier log ID can be provided in ShortText for debugging.

Error Type Code 2: No Implementation

Error Code Description Example
1 Not implemented The supplier can respond with this error if the end point called is not yet implemented.

Error Type Code 13: Application Error

Error Code Description Example
242 Credit card number is invalid or missing Missing credit card number.
320 Invalid value Comma separated node or attribute and sent value should be provided in the content of the error element. Example: <Error Code="320" ShortText="Invalid value" Type="13">StayDateRange:2019-11-33</Error>
322 No availability Hotel Codes should be provided in content of the element. Example: <Error Code="322" ShortText="No availability" Type="13">HTL4444,HTL5555</Error>
424 No hotels found which match this input Search parameters - geo-code and radius should be provided in content of the element and formatted as tokenized list: Latitude, Longitude, Radius, Unit of Measure code. Example: <Error Code="322" ShortText="No availability" Type="13">50.111,40.222,5,2</Error>
95 Booking already cancelled Booking already cancelled.
438 Requested rate not available List of comma separated RatePlanID's should be provided in content of the element. Example: <Error Code="322" ShortText="No availability" Type="13">111,222</Error>
748 Invalid corporate ID Requestor ID should be provided in the content of the element.
400 Invalid property code List of comma separated hotel codes should be provided in content of the element. Example: <Error Code="322" ShortText="No availability" Type="13">HTL4444,HTL5555</Error>
385 Invalid confirmation or cancellation number Reservation ID should be provided in content of the element.

Message to perform the initial search for hotels.

SOAPAction OTA Name Message Structure
search HotelSearch OTA_HotelSearchRQ

Search - Request

<Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">
  <Header xmlns="http://schemas.xmlsoap.org/soap/envelope/">
    <authentication xmlns="http://www.concur.com/webservice/auth">
      <userid>user</userid>
      <password>password</password>
    </authentication>
  </Header>
  <Body xmlns="http://schemas.xmlsoap.org/soap/envelope/">
    <OTA_HotelSearchRQ xmlns="http://www.opentravel.org/OTA/2003/05" EchoToken="test_request_id" Version="4"
                       PrimaryLangID="de" AltLangID="de" MaxResponses="100">
      <POS>
        <Source ISOCurrency="USD">
          <RequestorID Type="1" ID="47777"></RequestorID>
        </Source>
      </POS>
      <Criteria>
        <Criterion>
          <Position Latitude="52.520007" Longitude="13.404954"></Position>
          <RefPoint></RefPoint>
          <HotelRef HotelName="sunshine"></HotelRef>
          <Radius Distance="5" DistanceMax="30" UnitOfMeasureCode="1"></Radius>
          <StayDateRange Start="2018-09-26" End="2018-09-27"></StayDateRange>
        </Criterion>
      </Criteria>
      <TPA_Extensions>
        <CustomFields>
          <CustomField Name="OrgUnit" Value="Travel Agents"></CustomField>
        </CustomFields>
      </TPA_Extensions>
    </OTA_HotelSearchRQ>
  </Body>
</Envelope>

OTA_HotelSearchRQ

Name Type Description
MaxResponses integer Required SAP Concur currently supports 100 search results in one (1) message. If more than 100 results are returned SAP Concur drops all results after the 100th entry.
Criteria complex Required Specified hotel search criteria.
TPA_Extensions complex This adds an Org Unit name to the Search request.

Criteria

Name Type Description
Criterion complex Required Child elements that identify a single search criterion by criteria type.

Criterion

The criterion is used to define the search criteria. Currently we support only one Criterion.

Name Type Description
Position complex Required for Search request only, but optional for Availability request. Used to specify the geographic coordinates of a location, expressed in notation specified by ISO standard 6709.
HotelRef complex Indicates the detail of hotel reference information.
RefPoint stringLength0to64 The reference point element allows for a search by proximity to a designated reference point by name.
Radius complex Used to specify the extent of a search area. The extent is relative to an element (position, address, hotelRef, etc.) present in this ItemSearchCriterionType that specifies a location.
StayDateRange complex Required Range of dates using ISO 8601.

TPA_Extensions

Name Type Description
CustomFields complex This adds Org Unit name.

Search - CustomFields

Name Type Description
CustomField - -
Name xs:string -
Value xs:string -

Position

Name Type Description
Latitude stringLength1to16 Required The measure of the angular distance on a meridian north or south of the equator.
Longitude stringLength1to16 Required The measure of the angular distance on a meridian east or west of the prime meridian.

HotelRef

Name Type Description
HotelName stringLength1to128 A text field used to communicate the proper name of the hotel.

Radius

The radius element is used along with the Hotel Preference to categorize the search results.

Name Type Description
Distance stringLength1to16 Required The distance from a reference point.
DistanceMax stringLength1to16 Attribute indicating the distance from a reference point or Preferred (Corporate) hotels.
UnitOfMeasureCode stringLength1to16 Required The unit of measure in a code format. Refer to OpenTravel Code List of Measure Code (UOM). SAP uses 1 for miles, 2 for kilometers.

StayDateRange

Name Type Description
Start date, time, or datetime Required The starting value of the time span.
End date, time, or datetime Required The ending value of the time span.

Search - Response

The maximum allowed size of OTA_HotelSearchRS is 1 MB. Any response that exceeds this limit will be dropped.

<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <SOAP-ENV:Header xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"/>
  <soap:Body>
    <OTA_HotelSearchRS xmlns="http://www.opentravel.org/OTA/2003/05" AltLangID="EN" PrimaryLangID="EN" Version="4">
      <Success/>
      <Properties>
        <Property ChainCode="AB" ChainName="1111" HotelCode="22222" HotelName="Sunshine Hotel">
          <Position Latitude="52.4567" Longitude="13.5635"/>
          <Address>
            <AddressLine>An der Wuhlheide</AddressLine>
            <CityName>Berlin</CityName>
            <PostalCode>10115</PostalCode>
            <CountryName Code="DE">Federal Republic of Germany</CountryName>
          </Address>
          <ContactNumbers>
            <ContactNumber CountryAccessCode="49" PhoneNumber="56940033" PhoneTechType="1"/>
          </ContactNumbers>
          <Award Rating="4"/>
          <HotelAmenity Code="68"/>
          <TPA_Extensions>
            <HotelPreference>not_preferred</HotelPreference>
            <TPA_HotelPreviewImageURI>
              <URL>url_to_the_picture.jpg</URL>
            </TPA_HotelPreviewImageURI>
          </TPA_Extensions>
        </Property>
      </Properties>
      <TPA_Extensions>
        <SearchSessionToken>5EA6C45E55104704E4</SearchSessionToken>
      </TPA_Extensions>
    </OTA_HotelSearchRS>
  </soap:Body>
</soap:Envelope>

OTA_HotelSearchRS

Name Type Description
Properties complex Required A collection of individual property information.
TPA_Extensions/SearchSessionToken stringLength1to128 Optional A token that links the Search results to Availability and Reservation requests.

Properties

Name Type Description
Property complex Required A property that matches some or all of the search criteria.

Property

Name Type Description
ChainCode stringLength1to32 2-letter valid GDS chain code. The code that identifies a hotel chain or management group. Must be present to support filtering, preferences or travel rules base on chains
ChainName stringLength1to32 The name of the hotel chain. Examples: Hilton, Marriott, Hyatt, Starwood
HotelCode stringLength1to32 Required The code that uniquely identifies a single hotel property. Used in other OTA messages.
HotelName stringLength1to32 Required A text field used to communicate the proper name of the hotel.
Position complex Required Refer to Position in the Request.
Address complex Required Public address of the hotel property.
ContactNumbers complex Contact numbers.
Award complex An element that identifies the hotel ratings.
HotelAmenity complex List of hotel amenities.
TPA_Extensions complex SAP Concur-specific extension of OTA spec. This adds support for extra property fields.

Search - Address

Name Type Description
AddressLine stringLength1to255 The screenname and number. Maximum occurrences: 5
CityName stringLength1to64 Name of the city.
PostalCode stringLength1to16 The postal code.
StateProv complex Name of the state.
CountryName complex Country name. Example: Ireland

StateProv

Name Type Description
StateCode stringLength0to64 The standard code or abbreviation for the state, province, or region (note the code may not be available for all states).

CountryName

Name Type Description
Code stringLength0to64 Required The name or ISO 3166 code of a country.

ContactNumbers

Name Type Description
ContactNumber `complex Element which contains the ContactNumber. SAP Concur only accepts one (first) ContactNumber of each supported type.

ContactNumber

Name Type Description
CountryAccessCode stringLength1to32 The country code.
PhoneNumber stringLength1to32 Required The phone number.
PhoneTechType string SAP Concur currently only supports a PhoneTechType set to 1 (phone) or 3 (fax). You can omit this field only in case you are providing one contact number. We suggest to fill the type in all cases, it may become mandatory in the future.

Award

Name Type Description
Rating integer Required Hotel rating should be an integer number from 0 to 5, representing its star rating.

HotelAmenity

Name Type Description
Code string Required Refer to OpenTravel Code List Hotel Amenity Code (HAC).

TPA Extensions

Name Type Description
HotelPreference stringLength1to32 Required SAP Concur allows customers to override property preference in the system settings. Supported values: not_preferred, less_preferred, preferred, most_preferred
TPA_HotelPreviewImageURI complex Required Details for an image of a given category.

TPA_HotelPreviewImageURI

Name Type Description
URL stringLength1to32 Required URL of the multimedia item for a specific format. SAP Concur supports one image URL in the Search Response. For the ability to display more images refer to Descriptive Info message. The image will be used as a thumbnail and should be limited to 70x70 pixels to prevent image artifacts by scaling.

Availability

Message to retrieved the availability of hotels.

SOAPAction OTA Name Message Structure
availability HotelAvail OTA_HotelAvailRQ

Availability Request

<Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">
  <Header xmlns="http://schemas.xmlsoap.org/soap/envelope/">
    <authentication xmlns="http://www.concur.com/webservice/auth">
      <userid>user</userid>
      <password>password</password>
    </authentication>
  </Header>
  <Body xmlns="http://schemas.xmlsoap.org/soap/envelope/">
    <OTA_HotelAvailRQ xmlns="http://www.opentravel.org/OTA/2003/05" EchoToken="test_request_id" Version="5"
                      PrimaryLangID="de" AltLangID="de">
      <POS>
        <Source ISOCurrency="USD">
          <RequestorID Type="1" ID="1234567"></RequestorID>
        </Source>
      </POS>
      <AvailRequestSegments>
        <AvailRequestSegment>
          <HotelSearchCriteria>
            <Criterion>
              <HotelRef ChainCode="ZZ" HotelCode="111222"></HotelRef>
            </Criterion>
          </HotelSearchCriteria>
          <StayDateRange Start="2018-10-26" End="2018-10-28"></StayDateRange>
          <RoomStayCandidates>
            <RoomStayCandidate>
              <GuestCounts>
                <GuestCount AgeQualifyingCode="10" Count="1"></GuestCount>
              </GuestCounts>
            </RoomStayCandidate>
          </RoomStayCandidates>
          <TPA_Extensions>
            <SearchSessionToken>5EA6C45E55104704E4</SearchSessionToken>
          </TPA_Extensions>
        </AvailRequestSegment>
      </AvailRequestSegments>
    </OTA_HotelAvailRQ>
  </Body>
</Envelope>

Availability Schema

OTA_HotelAvailRQ

Name Type Description
AvailRequestSegments complex Required A collection of AvailRequestSegment. Each segment includes a collection of criteria that requests a bookable entity, which may include designated rate plans, room types, amenities or services. The request can be used for guest rooms or other inventory items for which availability is sought. Each segment will be presumed to have a unique date range for each request. SAP Concur will only ever send one AvailRequestSegments.

AvailRequestSegments

Name Type Description
AvailRequestSegment complex Required To accommodate the ability to perform multiple requests within one message, the availability request contains the repeating element, AvailRequestSegment. Each segment includes a collection of criteria that requests a bookable entity, which may include designated rate plans, room types, amenities or services. The request can be used for guest rooms or other inventory items for which availability is sought. Each segment will be presumed to have a unique date range for each request. SAP Concur will only ever send one AvailRequestSegment.

AvailRequestSegment

Name Type Description
HotelSearchCriteria complex Required Specified hotel search criteria. SAP Concur will send only one (1) HotelSearchCriteria.
StayDateRange complex Range of dates using ISO 8601.
TPA_Extensions/SearchSessionToken stringLength1to128 The token obtained from Search response that links the Search results to Availability and [Reservation]#reservation) requests.

HotelSearchCriteria

Name Type Description
Criterion complex Required Refer to Criterion in Search. Note that for Availability the Criterion will only have the HotelRef element. Other elements will not be sent. HotelSearchCriteria can contain multiple Criterion elements. Each will have a unique HotelCode per Availability request.

Availability - Criterion

Name Type Description
HotelRef/HotelCode stringLength1to16 The code that uniquely identifies a single hotel property. The hotel code is decided by vendors.
HotelRef/ChainCode stringLength1to8 The code that identifies a hotel chain or management group. The hotel chain code is decided between vendors. This attribute is optional if the hotel is an independent property that can be identified by the HotelCode attribute.

Availability - StayDateRange

Name Type Description
Start date, or time, or datetime Required The starting value of the time span.
End date, or time, or datetime Required The ending value of the time span.

RoomStayCandidates

Name Type Description
RoomStayCandidate complex Required Element used to identify available room products.

RoomStayCandidate

Name Type Description
GuestCounts complex Required A collection of guest counts associated with room stay.

GuestCounts

Name Type Description
GuestCount complex Required A recurring element that identifies the number of guests and ages of the guests. It currently contains hardcoded values only. See GuestCount below.

GuestCount

Name Type Description
Count integer Required SAP Concur only supports one guest. Supported values: 1
AgeQualifyingCode integer Required Supported values: 10

Availability Response

The maximum allowed size of OTA_HotelAvailRS is 5 MB. Any response that exceeds this limit shall be dropped.

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <SOAP-ENV:Header xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"/>
  <soap:Body>
    <OTA_HotelAvailRS xmlns="http://www.opentravel.org/OTA/2003/05" Version="5">
      <Success/>
      <RoomStays>
        <RoomStay>
          <RoomTypes>
            <RoomType RoomID="1">
              <RoomDescription>
                <Text>Test room description.</Text>
              </RoomDescription>
            </RoomType>
          </RoomTypes>
          <RatePlans>
            <RatePlan RatePlanID="XNFYP4I" AvailabilityStatus="ChangeDuringStay">
              <Guarantee>
                <Deadline AbsoluteDeadline="2017-01-26T18:00:00"/>
              </Guarantee>
              <CancelPenalties>
                <CancelPenalty>
                  <Deadline AbsoluteDeadline="2017-01-26T18:00:00"/>
                  <PenaltyDescription>
                    <Text>REFUNDABLE</Text>
                    <Text>test cancel description</Text>
                  </PenaltyDescription>
                </CancelPenalty>
              </CancelPenalties>
              <MealsIncluded Breakfast="true"/>
              <RatePlanDescription>
                <Text>Test rate plan description.</Text>
              </RatePlanDescription>
            </RatePlan>
          </RatePlans>
          <RoomRates>
            <RoomRate RoomID="1" RatePlanID="XNFYP4I">
              <Rates>
                <Rate RateTimeUnit="FullDuration">
                  <PaymentPolicies>
                    <GuaranteePayment>
                      <AcceptedPayments>
                        <AcceptedPayment>
                          <PaymentCard CardCode="VI"/>
                        </AcceptedPayment>
                      </AcceptedPayments>
                    </GuaranteePayment>
                  </PaymentPolicies>
                  <Total AmountAfterTax="348.00" AmountBeforeTax="248.00" CurrencyCode="EUR" DecimalPlaces="2"/>
                  <RateDescription>
                    <Text>Test rate description. Both before and after tax.</Text>
                  </RateDescription>
                  <TPA_Extensions>
                    <RequireSeriesCode>true</RequireSeriesCode>
                  </TPA_Extensions>
                </Rate>
              </Rates>
            </RoomRate>
          </RoomRates>
          <TimeSpan End="2018-10-28" Start="2018-10-26"/>
          <BasicPropertyInfo ChainCode="ZZ" HotelCode="419430"/>
        </RoomStay>
      </RoomStays>
      <TPA_Extensions RateDetailsInd="false"></TPA_Extensions>
    </OTA_HotelAvailRS>
  </soap:Body>
</soap:Envelope>

Schema

OTA_HotelAvailRS

Name Type Description
RoomStays complex Required A collection of details on the room stay including time span of this room stay, and financial information related to the room stay, including guarantee, deposit, payment, and cancellation penalties.
TPA_Extensions/RateDetailsInd boolean If true or omitted, ratedetails will not be called to retrieve the cancellation policy and rate change details; if false, ratedetails will be called.

RoomStays

Name Type Description
RoomStay complex Required Details on the room stay including time span of this room stay, and financial information related to the room stay, including guarantee, deposit, payment, and cancellation penalties. A room stay represents one (1) hotel.

RoomStay

For a description of the relationship between the RoomID and RatePlanID refer to "Relationship between RoomID and RatePlanID".

Name Type Description
RoomTypes complex Required Details on the room stay including guest counts, time span of this room stay, pointers to res guests, guest memberships, comments, and special requests pertaining to this particular room stay. Financial information related to the room stay, including guarantee, deposit, payment, and cancellation penalties.
RatePlans complex Required A collection of rate plans associated with a particular room stay. The rate plan element is used to contain all the rate information for a single rate plan Code (example: RACK) for a given date range. A given rate plan may have variable rates, over the effective period of the rate plan, this is represented by the child element rates.
RoomRates complex Required List of room rates.
TimeSpan datetimespan Required The time span which covers the room stay. The attributes of the OTA DateTimeSpan data type are based on the W3C base data types of timeInstant and timeDuration using ISO 8601.
BasicPropertyInfo complex Property Information for the room stay.

RoomTypes

Name Type Description
RoomType complex Required Provides details regarding rooms, usually guest rooms. The room description text will be used for each room (defined as a RoomRate) which specifies the same RoomID.

RoomType

Name Type Description
RoomID stringLength1to16 Required A string value representing the unique identification of a room if the request is looking for a specific room type.
RoomDescription complex Textual information regarding the room.

RoomDescription

Name Type Description
Text stringLength1to32 Required Only one (1) text element is supported. If multiple text elements are specified, the last one is used and all others are dropped. All text passed is HTML encoded.

RatePlans

Name Type Description
RatePlan complex Required Defines the details of the rate plan as used in the booking process. Policies and descriptions that apply to a rate plan. Information significant to defining a rate plan.

RatePlan

Name Type Description
RatePlanID stringLength1to64 Required A text field used to indicate a special ID code that is associated with the rate and is essential in the reservation request in order to obtain the rate. Examples: Corporate ID.
AvailabilityStatus stringLength1to32 Required Used to specify an availability status for the rate plan. Supported values: AvailableForSale, ChangeDuringStay.
Guarantee complex Required Guarantee information that applies to the rate plan. SAP Concur only expects one (1) Guarantee element per RatePlan.
CancelPenalties complex Required if RateDetailsInd is true or not present Collection of cancellation penalties. If the cancel penalties are not provided SAP Concur will display: "Cancellation policy not provided by vendor".
MealsIncluded complex Required if RateDetailsInd is true or not present Defines which meals are included with this rate program.
RatePlanDescription complex Textual information regarding the Rate Plan.

RatePlanDescription

Name Type Description
Text stringLength1to32 Required Only one (1) text element is supported. If multiple text elements are specified, the last one is used and all others are dropped. All text passed is HTML encoded.

Guarantee

Name Type Description
GuaranteeType string Required The guarantee information to hold a reservation.
Deadline complex Required Guarantee deadline, absolute or relative.

Supported GuaranteeTypes

GuaranteeType Description
Deposit In SAP Concur this value is seen as RequiredDeposit.
DepositRequired In SAP Concur this value is seen as RequiredDeposit.
CC/DC/Voucher In SAP Concur this value is seen as RequiredGuarantee.
PrePay In SAP Concur this value is seen as RequiredPrepay.
None In SAP Concur this value is seen as Never. No guarantee is required if user books a room with this type.
GuaranteeRequired RequiredGuarantee. If the Guarantee type cannot be mapped to any accepted type, it will be set to RequiredGuarantee. This value is the default.

Supported GuaranteeRequired

GuaranteeRequired Description
always Guarantee is required all the time independently on deposit account setting.
never Guarantee is never required.
default Guarantee is required if no deposit account is set up.

Deadline

Name Type Description
AbsoluteDeadline time or datetime Required Defines the absolute deadline. Either this or the offset attributes may be used.

CancelPenalties

Name Type Description
CancelPenalty complex Required Defines the cancellation penalty of the hotel facility.

CancelPenalty

Name Type Description
PenaltyDescription complex Text description of the penalty in a given language. This element may contain a maximum of 9 children text fields. Any excess text elements are dropped.
Deadline complex Required Cancellation deadline, absolute or relative. See Deadline above.

PenaltyDescription

Name Type Description
Text formattedText Required Formatted text content in a given language. All text passed is HTML encoded.

MealsIncluded

Name Type Description
Breakfast boolean Required If true, indicates breakfast is included. If false, indicates it is excluded. In both cases this information is shown to a customer in the rate description.

RoomRates

Name Type Description
RoomRate complex Required Contains the rate details.

RoomRate

Name Type Description
RoomID complex Required Room Type ID. The combination of RoomID and RatePlanID must be unique for a RoomStay.
RatePlanID complex Required Rate plan ID for which this rate is applicable for.
Rates complex Required Contains the rate for the given room. SAP Concur only expects one (1) rate inside the Rates element. Refer to Rate Details for rate change details.

Rates

Name Type Description
Rate complex Required Contains the rate for the given room. Only one (1) Rate element is expected. Refer to Rate Details for rate change details.

Rate

Name Type Description
RateTimeUnit string Indicates the time unit for the rate. Supported values: FullDuration, Day. Default: FullDuration
PaymentPolicies complex Payment policies for this rate.
Total complex Required A description of the rate.
RateDescription complex A textual description of a rate. Only one (1) Rate Description element is expected.
TPA_extensions complex TPA extensions for a rate.

PaymentPolicies

Name Type Description
GuaranteePayment complex Element containing the guarantee payment type.

GuaranteePayment

Name Type Description
AcceptedPayments complex Required If used, at least one (1) AcceptedPayment should be present.

AcceptedPayments

Name Type Description
AcceptedPayment complex Required Accepted payment type.

AcceptedPayment

Name Type Description
PaymentCard complex Required Description of payment type.

PaymentCard

Name Type Description
CardType complex Required String representation of a card type. Allowed values: AmericanExpress, BankOfAmerica, BritishAirways, CapitalOne, Chase, Citibank, ContinentalAirlines, DeltaAirlines, DiscoverCard, Disney, Eurocard, Hilton, Hyatt, Mariott, Mastercard, RitzCarlton, SouthwestAirlines, StarwoodHotels, UnitedAirlines, USAirways, VISA, Other_. See Code and Description if card type is other_.

CardType

Name Type Description
Code string If CardType is Other_, use this attribute for card code. Examples: AX, VI.
Description string If CardType is Other_, use this attribute for card description.

Total

Name Type Description
AmountBeforeTax string Required The total amount not including any associated tax. Examples: sales tax, VAT, GST
AmountAfterTax string Required The total amount including all associated taxes. Examples: sales tax, VAT, GST
CurrencyCode alphaLength3 Required Currency code.
DecimalPlaces integer Decimal places for currency code. This is an ISO 4217 standard "minor unit" for the number of decimal places for a particular currency.

RateDescription

Name Type Description
Text stringLength1to32 Required SAP Concur only expects one (1) text field for the rate description. Any excess text elements will be ignored. All text passed is HTML encoded.

Availability - TPA_Extensions

Name Type Description
RequireSeriesCode boolean Required If true, the CVV code is required for the given rate.

Timespan

Name Type Description
Start date, time, or datetime Required The starting value of the time span.
End date, time, or datetime Required The ending value of the time span.

BasicPropertyInfo

Name Type Description
HotelCode complex Required Refer to the HotelRef element described in Search.
Address complex Refer to Search.
ContactNumbers complex Refer to Search.

Relationship between RoomID and RatePlanID

The combination of these IDs must be unique per RoomStay. IDs with the same values can be redefined in multiple RoomStays.

<OTA_HotelAvailRS>
  <Success/>
  <!-- Hotel #1 with 3 rates -->
  <RoomStays>
    <RoomStay>
      <RoomTypes>
        <RoomType RoomID="RT1">...</RoomType>
        <RoomType RoomID="RT2">...</RoomType>
      </RoomTypes>
      <RatePlans> <!-- Contains cancellation policy info, guarantee type etc. -->
        <RatePlan AvailabilityStatus="AvailableForSale" PrepaidIndicator="false" RatePlanID="RP1">...</RatePlan>
        <RatePlan AvailabilityStatus="AvailableForSale" PrepaidIndicator="false" RatePlanID="RP2">...</RatePlan>
        <RatePlan AvailabilityStatus="AvailableForSale" PrepaidIndicator="false" RatePlanID="RP3">...</RatePlan>
      </RatePlans>
      <RoomRates> <!-- Represents unique rate (hotel room), contains description part 1, rate cost & supported credit card etc. -->
        <RoomRate RatePlanID="RP1" RoomID="RT1">...</RoomRate>
        <RoomRate RatePlanID="RP2" RoomID="RT2">...</RoomRate> <!-- Note: RT2 is reused in two Room Rates -->
        <RoomRate RatePlanID="RP3" RoomID="RT2">...</RoomRate>
      </RoomRates>
      ...
    </RoomStay>
  </RoomStays>
<!-- Hotel #2 with 2 rates -->
  <RoomStays>
    <RoomStay>
      <RoomTypes>
        <RoomType RoomID="RT1">...</RoomType>
        <RoomType RoomID="RT2">...</RoomType>
      </RoomTypes>
      <RatePlans>
        <RatePlan AvailabilityStatus="AvailableForSale" PrepaidIndicator="false" RatePlanID="RP1">...</RatePlan>
        <RatePlan AvailabilityStatus="AvailableForSale" PrepaidIndicator="false" RatePlanID="RP2">...</RatePlan>
      </RatePlans>
      <RoomRates>
        <RoomRate RatePlanID="RP1" RoomID="RT1">...</RoomRate>
        <RoomRate RatePlanID="RP2" RoomID="RT2">...</RoomRate>
      </RoomRates>
      ...
    </RoomStay>
  </RoomStays>
  ...
</OTA_HotelAvailRS>

Descriptive Information

Descriptive Info

Message to retrieve descriptive details about a given hotel. This may include text and/or a number of URL pointed to hosted images. Concur does not host any hotel images.

SOAPAction OTA Name Message Structure
detail HotelDescriptiveInfo OTA_HotelDescriptiveInfoRQ

Descriptive Info Request

<Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">
  <Header xmlns="http://schemas.xmlsoap.org/soap/envelope/">
    <authentication xmlns="http://www.concur.com/webservice/auth">
      <userid>user</userid>
      <password>password</password>
    </authentication>
  </Header>
  <Body xmlns="http://schemas.xmlsoap.org/soap/envelope/">
    <OTA_HotelDescriptiveInfoRQ xmlns="http://www.opentravel.org/OTA/2003/05" EchoToken="test_request_id" Version="3" PrimaryLangID="de" AltLangID="de">
      <POS>
        <Source ISOCurrency="USD">
          <RequestorID Type="1" ID="123"></RequestorID>
        </Source>
      </POS>
      <HotelDescriptiveInfos>
        <HotelDescriptiveInfo ChainCode="AB" HotelCode="2575"></HotelDescriptiveInfo>
      </HotelDescriptiveInfos>
    </OTA_HotelDescriptiveInfoRQ>
  </Body>
</Envelope>

OTA_HotelDescriptiveInfoRQ

Name Type Description
HotelDescriptiveInfos complex Required Collection of items for data from multiple hotels. SAP Concur will only ever send one (1) HotelDescriptiveInfo.

HotelDescriptiveInfos

Name Type Description
HotelDescriptiveInfo complex Required This allows the requestor to indicate which specific information is requested if complete hotel details are not required.

HotelDescriptiveInfo

Name Type Description
ChainCode stringLength1to8 The code that identifies a hotel chain or management group. The hotel chain code is decided between vendors. This attribute is optional if the hotel is an independent property that can be identified by the HotelCode attribute.
HotelCode stringLength1to16 Required The code that uniquely identifies a single hotel property. The hotel code is decided between vendors.

Descriptive Info Response

The maximum allowed size of OTA_HotelDescriptiveInfoRS is 150 KB. Any response that exceeds this limit will be dropped.

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <SOAP-ENV:Header xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"/>
  <soap:Body>
    <OTA_HotelDescriptiveInfoRS xmlns="http://www.opentravel.org/OTA/2003/05" Version="3">
      <Success/>
      <HotelDescriptiveContents>
        <HotelDescriptiveContent ChainCode="ZZ" HotelCode="2575" HotelName="Torbräu">
          <HotelInfo>
            <Descriptions>
              <DescriptiveText>Hotel description</DescriptiveText>
            </Descriptions>
          </HotelInfo>
          <MultimediaDescriptions>
            <MultimediaDescription>
              <ImageItems>
                <ImageItem>
                  <ImageFormat>
                    <URL>http://image_path.jpg</URL>
                  </ImageFormat>
                </ImageItem>
              </ImageItems>
            </MultimediaDescription>
          </MultimediaDescriptions>
          <TPA_Extensions>
            <Description Name="This will be a header">
              <Text>First line of first description.</Text>
              <Text>Second line of first description.</Text>
            </Description>
            <Description>
              <Text>Second description without name.</Text>
            </Description>
          </TPA_Extensions>
        </HotelDescriptiveContent>
      </HotelDescriptiveContents>
    </OTA_HotelDescriptiveInfoRS>
  </soap:Body>
</soap:Envelope>

OTA_HotelDescriptiveInfoRS

Name Type Description
HotelDescriptiveContents complex Required Contains hotel details content which is made up of text and image URLs.

HotelDescriptiveContents

Name Type Description
HotelDescriptiveContent `complex Required Contains hotel details content which is made up of text and image URLs. SAP Concur expects one (1) HotelDescriptiveContent.

HotelDescriptiveContent

Name Type Description
HotelCode stringLength1to16 Required The code that uniquely identifies a single hotel property. The hotel code is decided between vendors.
HotelName stringLength1to128 Required A text field used to communicate the proper name of the hotel. SAP Concur always expects the Hotel Name to be provided.
TPA_Extensions complex SAP Concur specific extensions.
MultimediaDescriptions complex Multimedia information about a collection of multimedia objects. SAP Concur expects one (1) MultimediaDescription element.

Descriptive Info - TPA_Extensions

Name Type Description
Description complex Represents text which will be rendered in the UI in the form of a heading and a paragraph.

Description

Name Type Description
name stringLength1to64 The contents of this element will be rendered as a heading on the hotel details page.
Text stringLength1to255 Required The contents of this element will be rendered as a paragraph. SAP Concur expects a maximum of 20 text elements per description, which will be concatenated to into one (1) paragraph.

MultimediaDescriptions

Name Type Description
MultimediaDescription complex Holds a list of ImageItems, each representing a single hotel image.

MultimediaDescription

Name Type Description
ImageItems complex Holds a list of ImageItem, each representing a single hotel image. SAP Concur expects up to a maximum of 200 ImageItem elements.

ImageItems

Name Type Description
ImageItem complex One (1) ImageItem per hotel image.

ImageItem

Name Type Description
ImageFormat complex Format of image.

ImageFormat

Name Type Description
URL stringLength1to32 Required Contains a HTTPS URL pointing to a hotel image. The URLs are used in a client-side gallery widget, which works best with .png and .jpg files.

Rate Details

Message to retrieved the details of a hotel rate.

SOAPAction OTA Name Message Structure
ratedetails HotelAvail OTA_HotelAvailRQ

Rate Details Request

<Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">
  <Header xmlns="http://schemas.xmlsoap.org/soap/envelope/">
    <authentication xmlns="http://www.concur.com/webservice/auth">
      <userid>user</userid>
      <password>password</password>
    </authentication>
  </Header>
  <Body xmlns="http://schemas.xmlsoap.org/soap/envelope/">
    <OTA_HotelAvailRQ xmlns="http://www.opentravel.org/OTA/2003/05" EchoToken="test_request_id" Version="5"
                      PrimaryLangID="de" AltLangID="de" RateDetailsInd="true">
      <POS>
        <Source ISOCurrency="USD">
          <RequestorID Type="1" ID="1234567"></RequestorID>
        </Source>
      </POS>
      <AvailRequestSegments>
        <AvailRequestSegment>
          <HotelSearchCriteria>
            <Criterion>
              <RatePlanCandidates>
                <RatePlanCandidate RatePlanID="XNFYP4I">
                  <HotelRefs>
                    <HotelRef ChainCode="ZZ" HotelCode="111222"></HotelRef>
                  </HotelRefs>
                </RatePlanCandidate>
              </RatePlanCandidates>
            </Criterion>
          </HotelSearchCriteria>
          <StayDateRange Start="2018-10-26" End="2018-10-28"></StayDateRange>
          <RoomStayCandidates>
            <RoomStayCandidate>
              <GuestCounts>
                <GuestCount AgeQualifyingCode="10" Count="1"></GuestCount>
              </GuestCounts>
            </RoomStayCandidate>
          </RoomStayCandidates>
          <TPA_Extensions>
            <SearchSessionToken>5EA6C45E55104704E4</SearchSessionToken>
          </TPA_Extensions>
        </AvailRequestSegment>
      </AvailRequestSegments>
    </OTA_HotelAvailRQ>
  </Body>
</Envelope>

Rate Details Schema

OTA_HotelAvailRQ

Name Type Description
RateDetailsInd boolean Required Always set to true for ratedetails.
AvailRequestSegments complex Required A collection of AvailRequestSegment. Each segment includes a collection of criteria that requests a bookable entity, which may include designated rate plans, room types, amenities or services. The request can be used for guest rooms or other inventory items for which availability is sought. Each segment will be presumed to have a unique date range for each request. SAP Concur will only ever send one AvailRequestSegments.

Rate Details - AvailRequestSegments

Name Type Description
AvailRequestSegment complex Required To accommodate the ability to perform multiple requests within one message, the availability request contains the repeating element, AvailRequestSegment. Each segment includes a collection of criteria that requests a bookable entity, which may include designated rate plans, room types, amenities or services. The request can be used for guest rooms or other inventory items for which availability is sought. Each segment will be presumed to have a unique date range for each request. SAP Concur will only ever send one AvailRequestSegment.

Rate Details - AvailRequestSegment

Name Type Description
HotelSearchCriteria complex Required Specified hotel search criteria. SAP Concur will send only one (1) HotelSearchCriteria.
StayDateRange complex Range of dates using ISO 8601.
TPA_Extensions/SearchSessionToken stringLength1to128 The token obtained from Search response that links the Search results to Availability and Reservation requests.

Rate Details - HotelSearchCriteria

Name Type Description
Criterion complex Required Refer to Criterion in Search. Note that for Rate Details the Criterion will only have one RatePlanCandidate element.

Rate Details - Criterion

Name Type Description
RatePlanCandidates/RatePlanCandidate complex Required Specified rate plan candidate.

Rate Details - RatePlanCandidate

Name Type Description
RatePlanID StringLength1to64 Required The code that uniquely identifies the rate plan.
HotelRefs/HotelRef/HotelCode stringLength1to16 The code that uniquely identifies a single hotel property. The hotel code is decided by vendors.
HotelRefs/HotelRef/ChainCode stringLength1to8 The code that identifies a hotel chain or management group. The hotel chain code is decided between vendors. This attribute is optional if the hotel is an independent property that can be identified by the HotelCode attribute.

Rate Details - StayDateRange

Name Type Description
Start date, or time, or datetime Required The starting value of the time span.
End date, or time, or datetime Required The ending value of the time span.

Rate Details - RoomStayCandidates

Name Type Description
RoomStayCandidate complex Required Element used to identify available room products.

Rate Details - RoomStayCandidate

Name Type Description
GuestCounts complex Required A collection of guest counts associated with room stay.

Rate Details - GuestCounts

Name Type Description
GuestCount complex Required A recurring element that identifies the number of guests and ages of the guests. It currently contains hardcoded values only. See GuestCount below.

Rate Details - GuestCount

Name Type Description
Count integer Required SAP Concur only supports one guest. Supported values: 1
AgeQualifyingCode integer Required Supported values: 10

Rate Details - Response

The maximum allowed size of OTA_HotelAvailRS is 5 MB. Any response that exceeds this limit shall be dropped.

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <SOAP-ENV:Header xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"/>
  <soap:Body>
    <OTA_HotelAvailRS xmlns="http://www.opentravel.org/OTA/2003/05" Version="5">
      <Success/>
      <RoomStays>
        <RoomStay>
          <RoomTypes>
            <RoomType RoomID="1">
              <RoomDescription>
                <Text>Test room description.</Text>
              </RoomDescription>
            </RoomType>
          </RoomTypes>
          <RatePlans>
            <RatePlan RatePlanID="XNFYP4I" AvailabilityStatus="ChangeDuringStay">
              <Guarantee>
                <Deadline AbsoluteDeadline="2017-01-26T18:00:00"/>
              </Guarantee>
              <CancelPenalties>
                <CancelPenalty>
                  <Deadline AbsoluteDeadline="2017-01-26T18:00:00"/>
                  <PenaltyDescription>
                    <Text>REFUNDABLE</Text>
                    <Text>test cancel description</Text>
                  </PenaltyDescription>
                </CancelPenalty>
              </CancelPenalties>
              <MealsIncluded Breakfast="true"/>
              <RatePlanDescription>
                <Text>Test rate plan description.</Text>
              </RatePlanDescription>
            </RatePlan>
          </RatePlans>
          <RoomRates>
            <RoomRate RoomID="1" RatePlanID="XNFYP4I">
              <RoomRateDescription>
                <Text>Basic Wifi Included.</Text>
              </RoomRateDescription>
              <Rates>
                <Rate RateTimeUnit="FullDuration" EffectiveDate="2018-10-26" ExpireDate="2018-10-27">
                  <PaymentPolicies>
                    <GuaranteePayment>
                      <AcceptedPayments>
                        <AcceptedPayment>
                          <PaymentCard CardCode="VI"/>
                        </AcceptedPayment>
                      </AcceptedPayments>
                    </GuaranteePayment>
                  </PaymentPolicies>
                  <Total AmountAfterTax="199.00" AmountBeforeTax="149.00" CurrencyCode="EUR" DecimalPlaces="2"/>
                  <RateDescription>
                    <Text>Test rate description. Both before and after tax.</Text>
                  </RateDescription>
                  <TPA_Extensions>
                    <RequireSeriesCode>true</RequireSeriesCode>
                  </TPA_Extensions>
                </Rate>
                <Rate RateTimeUnit="FullDuration" EffectiveDate="2018-10-27" ExpireDate="2018-10-28">
                    <Total AmountAfterTax="149.00" AmountBeforeTax="99.00" CurrencyCode="EUR" DecimalPlaces="2"/>
                </Rate>
              </Rates>
            </RoomRate>
          </RoomRates>
          <TimeSpan End="2018-10-28" Start="2018-10-26"/>
          <BasicPropertyInfo ChainCode="ZZ" HotelCode="419430"/>
        </RoomStay>
      </RoomStays>
      <TPA_Extensions RateDetailsInd="true"></TPA_Extensions>
    </OTA_HotelAvailRS>
  </soap:Body>
</soap:Envelope>

Rate Details - Schema

OTA_HotelAvailRS

Name Type Description
RoomStays complex Required A collection of details on the room stay including time span of this room stay, and financial information related to the room stay, including guarantee, deposit, payment, and cancellation penalties.
TPA_Extensions/RateDetailsInd boolean Always set to true for ratedetails.

Rate Details - RoomStays

Name Type Description
RoomStay complex Required Details on the room stay including time span of this room stay, and financial information related to the room stay, including guarantee, deposit, payment, and cancellation penalties. A room stay represents one (1) hotel.

Rate Details - RoomStay

For a description of the relationship between the RoomID and RatePlanID refer to "Relationship between RoomID and RatePlanID".

Name Type Description
RoomTypes complex Required Details on the room stay including guest counts, time span of this room stay, guest memberships, comments, and special requests pertaining to this particular room stay. Financial information related to the room stay, including guarantee, deposit, payment, and cancellation penalties.
RatePlans complex Required A collection of rate plans associated with a particular room stay. The rate plan element is used to contain all the rate information for a single rate plan Code (example: RACK) for a given date range. A given rate plan may have variable rates, over the effective period of the rate plan, this is represented by the child element rates.
RoomRates complex Required List of room rates.
TimeSpan datetimespan Required The time span which covers the room stay. The attributes of the OTA DateTimeSpan data type are based on the W3C base data types of timeInstant and timeDuration using ISO 8601.
BasicPropertyInfo complex Property Information for the room stay.

Rate Details - RoomTypes

Name Type Description
RoomType complex Required Provides details regarding rooms, usually guest rooms. The room description text will be used for each room (defined as a RoomRate) which specifies the same RoomID.

Rate Details - RoomType

Name Type Description
RoomID stringLength1to16 Required A string value representing the unique identification of a room if the request is looking for a specific room type.
RoomDescription complex Textual information regarding the room.

Rate Details - RoomDescription

Name Type Description
Text stringLength1to32 Required Only one (1) text element is supported. If multiple text elements are specified, the last one is used and all others are dropped. All text passed is HTML encoded.

Rate Details - RatePlans

Name Type Description
RatePlan complex Required Defines the details of the rate plan as used in the booking process. Policies and descriptions that apply to a rate plan. Information significant to defining a rate plan.

Rate Details - RatePlan

Name Type Description
RatePlanID stringLength1to64 Required A text field used to indicate a special ID code that is associated with the rate and is essential in the reservation request in order to obtain the rate. Examples: Corporate ID.
AvailabilityStatus stringLength1to32 Required Used to specify an availability status for the rate plan. Supported values: AvailableForSale, ChangeDuringStay.
Guarantee complex Required Guarantee information that applies to the rate plan. SAP Concur only expects one (1) Guarantee element per RatePlan.
CancelPenalties complex Required if RateDetailsInd is true Collection of cancellation penalties. If the cancel penalties are not provided SAP Concur will display: "Cancellation policy not provided by vendor".
MealsIncluded complex Required if RateDetailsInd is true Defines which meals are included with this rate program.
RatePlanDescription complex Textual information regarding the Rate Plan.

Rate Details - RatePlanDescription

Name Type Description
Text stringLength1to32 Required Only one (1) text element is supported. If multiple text elements are specified, the last one is used and all others are dropped. All text passed is HTML encoded.

Rate Details - Guarantee

Name Type Description
GuaranteeType string Required The guarantee information to hold a reservation.
Deadline complex Required Guarantee deadline, absolute or relative.

Rate Details - Supported GuaranteeTypes

GuaranteeType Description
Deposit In SAP Concur this value is seen as RequiredDeposit.
DepositRequired In SAP Concur this value is seen as RequiredDeposit.
CC/DC/Voucher In SAP Concur this value is seen as RequiredGuarantee.
PrePay In SAP Concur this value is seen as RequiredPrepay.
None In SAP Concur this value is seen as Never. No guarantee is required if user books a room with this type.
GuaranteeRequired RequiredGuarantee. If the Guarantee type cannot be mapped to any accepted type, it will be set to RequiredGuarantee. This value is the default.

Rate Details - Supported GuaranteeRequired

GuaranteeRequired Description
always Guarantee is required all the time independently on deposit account setting.
never Guarantee is never required.
default Guarantee is required if no deposit account is set up.

Rate Details - Deadline

Name Type Description
AbsoluteDeadline time or datetime Required Defines the absolute deadline. Either this or the offset attributes may be used.

Rate Details - CancelPenalties

Name Type Description
CancelPenalty complex Required Defines the cancellation penalty of the hotel facility.

Rate Details - CancelPenalty

Name Type Description
PenaltyDescription complex Text description of the penalty in a given language. This element may contain a maximum of 9 children text fields. Any excess text elements are dropped.
Deadline complex Required Cancellation deadline, absolute or relative. See Deadline above.

Rate Details - PenaltyDescription

Name Type Description
Text formattedText Required Formatted text content in a given language. All text passed is HTML encoded.

Rate Details - MealsIncluded

Name Type Description
Breakfast boolean Required If true, indicates breakfast is included. If false, indicates it is excluded. In both cases this information is shown to a customer in the rate description.

Rate Details - RoomRates

Name Type Description
RoomRate complex Required Contains the rate details.

Rate Details - RoomRate

Name Type Description
RoomID complex Required Room Type ID. The combination of RoomID and RatePlanID must be unique for a RoomStay.
RatePlanID complex Required Rate plan ID for which this rate is applicable for.
Rates complex Required Contains the rate for the given room. SAP Concur only expects one (1) Rate inside the Rates element if AvailabilityStatus is AvailableForSale. It is optional to include multiple Rate for ChangeDuringStay
RoomRateDescription complex The description or name of a room rate.

Rate Details - Rates

Name Type Description
Rate complex Required Contains the rate for the given room. Only one (1) Rate element is expected if AvailabilityStatus is AvailableForSale. It is optional to include multiple Rate for ChangeDuringStay

Rate Details - Rate

Name Type Description
RateTimeUnit string Indicates the time unit for the rate. Supported values: FullDuration, Day. Default: FullDuration
EffectiveDate date, or time, or datetime For ChangeDuringStay. The starting value of the time span.
ExpireDate date, or time, or datetime For ChangeDuringStay. The starting value of the time span.
PaymentPolicies complex Payment policies for this rate.
Total complex Required A description of the rate.
RateDescription complex A textual description of a rate. Only one (1) Rate Description element is expected.
TPA_extensions complex TPA extensions for a rate.

Rate Details - RoomRateDescription

Name Type Description
Text formattedText Required Formatted text content in a given language. All text passed is HTML encoded.

Rate Details - PaymentPolicies

Name Type Description
GuaranteePayment complex Element containing the guarantee payment type.

Rate Details - GuaranteePayment

Name Type Description
AcceptedPayments complex Required If used, at least one (1) AcceptedPayment should be present.

Rate Details - AcceptedPayments

Name Type Description
AcceptedPayment complex Required Accepted payment type.

Rate Details - AcceptedPayment

Name Type Description
PaymentCard complex Required Description of payment type.

Rate Details - PaymentCard

Name Type Description
CardType complex Required String representation of a card type. Allowed values: AmericanExpress, BankOfAmerica, BritishAirways, CapitalOne, Chase, Citibank, ContinentalAirlines, DeltaAirlines, DiscoverCard, Disney, Eurocard, Hilton, Hyatt, Mariott, Mastercard, RitzCarlton, SouthwestAirlines, StarwoodHotels, UnitedAirlines, USAirways, VISA, Other_. See Code and Description if card type is other_.

Rate Details - CardType

Name Type Description
Code string If CardType is Other_, use this attribute for card code. Examples: AX, VI.
Description string If CardType is Other_, use this attribute for card description.

Rate Details - Total

Name Type Description
AmountBeforeTax string Required The total amount not including any associated tax. Examples: sales tax, VAT, GST
AmountAfterTax string Required The total amount including all associated taxes. Examples: sales tax, VAT, GST
CurrencyCode alphaLength3 Required Currency code.
DecimalPlaces integer Decimal places for currency code. This is an ISO 4217 standard "minor unit" for the number of decimal places for a particular currency.

Rate Details - RateDescription

Name Type Description
Text stringLength1to32 Required SAP Concur only expects one (1) text field for the rate description. Any excess text elements will be ignored. All text passed is HTML encoded.

Rate Details - TPA_Extensions

Name Type Description
RequireSeriesCode boolean Required If true, the CVV code is required for the given rate.

Rate Details - Timespan

Name Type Description
Start date, time, or datetime Required The starting value of the time span.
End date, time, or datetime Required The ending value of the time span.

Rate Details - BasicPropertyInfo

Name Type Description
HotelCode complex Required Refer to the HotelRef element described in Search.
Address complex Refer to Search.
ContactNumbers complex Refer to Search.

Reservation

Reservation Message

Message to reserve a hotel.

SOAPAction OTA Name Message Structure
book HotelRes OTA_HotelResRQ

Reservation Request

<Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">
  <Header xmlns="http://schemas.xmlsoap.org/soap/envelope/">
    <authentication xmlns="http://www.concur.com/webservice/auth">
      <userid>user</userid>
      <password>password</password>
    </authentication>
  </Header>
  <Body xmlns="http://schemas.xmlsoap.org/soap/envelope/">
    <OTA_HotelResRQ xmlns="http://www.opentravel.org/OTA/2003/05" EchoToken="test_request_id" Version="6"
                    PrimaryLangID="de" AltLangID="de">
      <POS>
        <Source ISOCurrency="USD">
          <RequestorID Type="4" ID="s1"></RequestorID>
        </Source>
      </POS>
      <HotelReservations>
        <HotelReservation>
          <RoomStays>
            <RoomStay>
              <RatePlans>
                <RatePlan RatePlanID="ZZZZ1117">
                  <Guarantee GuaranteeType="CC/DC/Voucher">
                    <GuaranteesAccepted>
                      <GuaranteeAccepted>
                        <PaymentCard CardCode="VI" ExpireDate="1018">
                          <CardType Code="VI">VISA</CardType>
                          <CardHolderName>Jane Doe</CardHolderName>
                          <Address>
                            <StreetNmbr>600 13TH ST NE</StreetNmbr>
                            <CityName>WASHINGTON</CityName>
                            <PostalCode>20002</PostalCode>
                            <StateProv StateCode="DC"></StateProv>
                            <CountryName>US</CountryName>
                          </Address>
                          <SeriesCode>
                            <PlainText>xxx</PlainText>
                          </SeriesCode>
                        </PaymentCard>
                      </GuaranteeAccepted>
                    </GuaranteesAccepted>
                  </Guarantee>
                </RatePlan>
              </RatePlans>
              <TimeSpan Start="2017-01-26" End="2017-01-27"></TimeSpan>
              <BasicPropertyInfo HotelCode="111222"></BasicPropertyInfo>
              <Comments>
                <Comment>
                  <Text TextFormat="PlainText">ROLLAWAY</Text>
                </Comment>
                <Comment>
                  <Text TextFormat="PlainText">FOAMPILLOWS</Text>
                </Comment>
              </Comments>
            </RoomStay>
          </RoomStays>
          <ResGuests>
            <ResGuest>
              <Profiles>
                <ProfileInfo>
                  <Profile>
                    <Customer Gender="Female" BirthDate="1987-05-12">
                      <PersonName Language="de">
                        <NamePrefix>MRS</NamePrefix>
                        <GivenName>JANE</GivenName>
                        <Surname>DOE</Surname>
                      </PersonName>
                      <Telephone PhoneNumber="703-837-6100"></Telephone>
                      <Email>jane.doe@example.com</Email>
                      <Address>
                        <AddressLine>209 Madison St Suite 400</AddressLine>
                        <CityName>Alexandria</CityName>
                        <PostalCode>22314</PostalCode>
                        <StateProv StateCode="VA"></StateProv>
                        <CountryName Code="US">USA</CountryName>
                      </Address>
                      <CitizenCountryName Code="US"></CitizenCountryName>
                    </Customer>
                    <CompanyInfo>
                      <CompanyName>SAP Concur</CompanyName>
                    </CompanyInfo>
                  </Profile>
                </ProfileInfo>
              </Profiles>
              <GuestCounts>
                <GuestCount Count="1"></GuestCount>
              </GuestCounts>
            </ResGuest>
          </ResGuests>
          <ResGlobalInfo>
            <Memberships>
              <Membership ProgramCode="HotelLoyaltyProgram" AccountID="1111111"></Membership>
            </Memberships>
          </ResGlobalInfo>
          <TPA_Extensions>
            <SearchSessionToken>5EA6C45E55104704E4</SearchSessionToken>
          </TPA_Extensions>
        </HotelReservation>
        <TPA_Extensions>
          <NotifyEmails>
            <NotifyEmails>jane.doe@example.com</NotifyEmails>
            <NotifyEmails>a@b.cz</NotifyEmails>
            <NotifyEmails>d@f.cz</NotifyEmails>
          </NotifyEmails>
          <CustomFields>
            <CustomField Name="trip1" Value="value1t"></CustomField>
            <CustomField Name="trip2" Value="value2t"></CustomField>
            <CustomField Name="user1" Value="value1u"></CustomField>
            <CustomField Name="user2"></CustomField>
          </CustomFields>
        </TPA_Extensions>
      </HotelReservations>
    </OTA_HotelResRQ>
  </Body>
</Envelope>

OTA_HotelResRQ

Name Type Description
HotelReservations complex Required A collection of hotel reservations. SAP Concur will only send one (1) hotel reservation.

Reservation - HotelReservation

Name Type Description
RoomStays complex Required A reference to identify the booking.
ResGuests complex Required List of guests. Supported value: 1
ResGlobalInfo complex Contains information that affects the reservation as a whole, typically a list of reward programs (see Memberships) or itinerary remarks (see Comments).
TPA_Extensions/SearchSessionToken stringLength1to128 The token obtained from Search response that links the Search results to Availability and Reservation requests.

RoomStays

Name Type Description
RatePlans complex Required Refer to RatePlans in Availability.
Timespan complex Required Refer to Time-span in Availability.
BasicPropertyInfo complex Required See Availability.
Comments complex Comments from the user which are passed on to the hotel.

Reservation - GuestCounts

Name Type Description
GuestCounts complex Required Please note: this field is currently being discussed with our partners as the plan to remove GuestCounts from OTA_HotelAvailRQ. A recurring element that identifies the number of guests.

Reservation - GuestCount

Name Type Description
Count integer Required Please note: this element is planned to be removed. A recurring element that identifies the number of guests and ages of the guests. The number of guests. Supported value: 1

RatePlan

Name Type Description
RatePlanID stringLength1to64 A text field used to provide a special ID code that is associated with the rate and is required in the reservation request in order to obtain the rate.
Guarantee complex Required Refer to Guarantee in Availability.

Reservation - Guarantee

Name Type Description
GuaranteeType stringLength1to32 Required Refer to GuaranteeType in Availability.
GuaranteesAccepted complex Required Guarantee and payment information.

GuaranteesAccepted

Name Type Description
Default boolean This is to indicate that the information in the model is the default (e.g. if PaymentCard information is completed then this would be considered the default if the boolean is true).
NoCardHolderInfoReqInd boolean If true, no credit card holder information is required. If false, it is required.
NameReqInd boolean If true, the credit card holder name is required. If false, it is not required.
AddressReqInd boolean If true, credit card holder address is required. If false, it is not required.
PhoneReqInd boolean If true, credit card holder phone number is required. If false, it is not required.
InterbankNbrReqInd boolean If true, the credit card interbank number is required. If false, it is not required.
PaymentCard complex Required Specific payment card information.

Reservation - PaymentCard

Name Type Description
CardCode upperCaseAlphaLength1to2 Issuer code. Example: MC, VI, AX.
ExpireDate MMYYDate Indicates the ending date.
CardType stringLength1to32 Required Payment card type. Example: MasterCard
CardHolderName stringLength1to32 Required Card holder name.
CardNumber complex Required The card number.
Address complex Required Refer to Address in Search.
SeriesCode complex Verification digits.

SeriesCode

Name Type Description
PlainText stringLength1to32 Required CVV number. Only one (1) element of this type is sent.

Comments

Name Type Description
Comment complex Required SAP Concur will send one Text element per Comment element.

Comment

Name Type Description
Text string Required Text representing the comment.

Text

Name Type Description
TextFormat stringLength1to32 Required Supported value: Plain text

ResGuest

Name Type Description
Profiles complex Required List of Profiles. SAP Concur will only send one (1) profile.

Profile

Name Type Description
Customer complex Required Element to describer a customer.
CompanyInfo complex Element to capture the company name.

Customer

Name Type Description
Gender string Gender. Supported values: Male, Female, Unknown, Male_NoShare, Female_NoShare
BirthDate date Customer's birthday.
PersonName complex Element representing a customer's name.
Telephone complex Element representing a telephone number.
Email stringLength1to32 Email address.
Address complex Refer to Address in Search.
CitizenCountryName complex ISO 3166 representation of the user's country as defined in their SAP Concur Profile.

PersonName

Name Type Description
NamePrefix stringLength1to16 Salutation of honorific. Supported values: Mr, Mrs, Ms, Miss, Dr, Rev, Sir, Lord, Lady, Dr Mr, Dr Mrs, Dr Ms, Prof Mr, Prof Mrs, Prof Ms, Prof Dr Mr, Prof Dr Mrs, Prof Dr Ms
GivenName stringLength1to64 Given name, first name or names.
Surname stringLength1to64 Required Family name, last name. May also be used for full name if the sending system does not have the ability to separate a full name into its parts. Example: the surname element may be used to pass the full name.

Telephone

Name Type Description
PhoneNumber stringLength1to32 Required A string representing a customer's phone number.

CitizenCountryName

Name Type Description
Code stringLength1to32 Required ISO 3166 country code.

CompanyInfo

Name Type Description
CompanyName stringLength1to32 Required A string representing a customer's company.

ResGlobalInfo

Note: This structure is used in both request and response. Different elements are used in each of them.

Name Type Description
Memberships complex Request Only A collection of memberships. Provides a list of reward programs. Example: loyalty cards
Comments complex Response Only A collection of comments. Provides a list of arbitrary reservation comments. Example: modification code
BasicPropertyInfo complex See Availability.

Memberships

Name Type Description
Membership complex A recurring element that identifies the type of reservation comment.

Membership

Name Type Description
ProgramCode stringLength1to32 Required The code or name of the reward program. Example: HotelLoyaltyProgram
AccountID stringLength1to64 Required The account identification number for this particular member in this particular program.

Comments

Name Type Description
Comment complex A recurring element that carries reservation comment. Maximum elements: 9

Comment

Name Type Description
Name stringLength1to64 Attribute containing comment title.
Text string Required Comment payload. Up to 3 Text elements in the comment. Up to 200 characters in the text.

Reservation - TPA Extensions

Name Type Description
NotifyEmails complex Email address which can be used by the vendor to contact the customer.
CustomFields complex A reference to identify the booking.

NotifyEmails

Name Type Description
NotifyEmails stringLength1to32 Required There will be one (1) NotifyEmails element per email address in the configuration.

Reservation CustomFields

Name Type Description
CustomField complex Required A custom field in the form of a key-value pair.

Reservation CustomField

Name Type Description
Name stringLength1to32 Required Name of the custom field.
Value stringLength1to32 Value of the custom field.

Reservation - Response

The maximum allowed size of OTA_HotelResRS is 150 KB. Any response that exceeds this limit shall be dropped.

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <SOAP-ENV:Header xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"/>
  <soap:Body>
    <OTA_HotelResRS xmlns="http://www.opentravel.org/OTA/2003/05" Version="6" ResResponseType="Reserved">
      <Success/>
      <HotelReservations>
        <HotelReservation>
          <UniqueID Type="14" ID="88618333"/>
          <UniqueID Type="1000" ID="12345"/>
          <RoomStays>
            <RoomStay>
              <RatePlans>
                <RatePlan RatePlanID="EZ57LL7">
                  <CancelPenalties CancelPolicyIndicator="true">
                    <CancelPenalty>
                      <PenaltyDescription>
                        <Text>test cancel policy 1</Text>
                      </PenaltyDescription>
                    </CancelPenalty>
                    <CancelPenalty>
                      <PenaltyDescription>
                        <Text>test cancel policy 2</Text>
                      </PenaltyDescription>
                      <PenaltyDescription>
                        <Text>test cancel policy 3</Text>
                      </PenaltyDescription>
                    </CancelPenalty>
                    <CancelPenalty>
                      <Deadline AbsoluteDeadline="2017-01-26T18:00"/>
                    </CancelPenalty>
                  </CancelPenalties>
                </RatePlan>
              </RatePlans>
              <RoomRates>
                <RoomRate>
                  <Rates>
                    <Rate>
                      <PaymentPolicies>
                        <GuaranteePayment>
                          <AcceptedPayments>
                            <AcceptedPayment>
                              <PaymentCard>
                                <CardType>VISA</CardType>
                              </PaymentCard>
                            </AcceptedPayment>
                          </AcceptedPayments>
                        </GuaranteePayment>
                        <GuaranteePayment>
                          <AcceptedPayments>
                            <AcceptedPayment>
                              <PaymentCard>
                                <CardType>Mastercard</CardType>
                              </PaymentCard>
                            </AcceptedPayment>
                          </AcceptedPayments>
                        </GuaranteePayment>
                        <GuaranteePayment>
                          <AcceptedPayments>
                            <AcceptedPayment>
                              <PaymentCard>
                                <CardType>AmericanExpress</CardType>
                              </PaymentCard>
                            </AcceptedPayment>
                          </AcceptedPayments>
                        </GuaranteePayment>
                      </PaymentPolicies>
                      <Total AmountAfterTax="185.00" AmountBeforeTax="85.00" CurrencyCode="EUR"/>
                    </Rate>
                  </Rates>
                </RoomRate>
              </RoomRates>
              <TimeSpan End="2017-01-27" Start="2017-01-26"/>
              <BasicPropertyInfo HotelCode="50709" HotelName="Alexander Plaza">
                <Address>
                  <AddressLine>Rosenstr. 1</AddressLine>
                  <CityName>Berlin</CityName>
                  <CountryName Code="DEU">Federal Republic of Germany</CountryName>
                  <StateProv StateCode="BE">Berlin District</StateProv>
                  <PostalCode>BE123</PostalCode>
                </Address>
                <ContactNumbers>
                  <ContactNumber PhoneNumber="1111111112" PhoneTechType="1"/>
                </ContactNumbers>
              </BasicPropertyInfo>
            </RoomStay>
          </RoomStays>
          <ResGuests>
            <ResGuest>
              <Profiles>
                <ProfileInfo>
                  <Profile>
                    <Customer>
                      <PersonName>
                        <GivenName>Jane</GivenName>
                        <Surname>Doe</Surname>
                      </PersonName>
                    </Customer>
                  </Profile>
                </ProfileInfo>
              </Profiles>
            </ResGuest>
          </ResGuests>
          <ResGlobalInfo>
            <Comments>
              <Comment Name="First Comment">
                <Text>First line of first comment</Text>
                <Text>Second line of first comment</Text>
              </Comment>
              <Comment>
                <Text>Second comment without name</Text>
              </Comment>
            </Comments>
          </ResGlobalInfo>
        </HotelReservation>
      </HotelReservations>
    </OTA_HotelResRS>
  </soap:Body>
</soap:Envelope>

OTA_HotelResRS

Name Type Description
ResResponseType stringLength1to32 Required See the list of possible values.
HotelReservations complex Required SAP Concur only supports one (1) reservation. All extra reservations will be ignored.

ResResponseType

Value Description
Cancelled -
Committed -
Unsuccessful -
Reserved The item is reserved.

Reservation - HotelReservations

Name Type Description
HotelReservation complex Required A reference to identify the booking.

Reservation - HotelReservation

Name Type Description
UniqueID complex Required A reference to identify the booking. Maximum occurrences: 2
RoomStays complex Required A collection of details on the room stay including time span of this room stay, and financial information related to the room stay, including guarantee, deposit, payment, and cancellation penalties.

UniqueID

Name Type Description
ID stringLength1to32 Required A reference to identify the booking.
Type stringLength1to32 Required A reference to identify the type of UniqueID. See Type.

Type - Possible Values

Value Description
14 Reservation ID used in subsequent calls (Itinerary, Cancel).
15 Cancellation number, displayed in UI, proof of cancellation.
40 Confirmation number for future use (not used now).
1000 Cancellation/modification code. This will be rendered on itinerary page and can be used to change the reservation outside of the SAP Concur system. SAP Concur-specific OTA extension.

Reservation - RoomStays

Name Type Description
RoomStay complex Required Details on the room stay including time span of this room stay, pointers to res guests, comments and special requests pertaining to this particular room stay. Financial information related to the room stay, including guarantee, deposit, payment, and cancellation penalties.

Reservation - RoomStay

Name Type Description
RatePlans complex Required A collection of rate plans associated with a particular room stay.

Reservation - RatePlan

Name Type Description
CancelPenalties complex Collection of cancellation penalties.
CancelPolicyIndicator boolean If true, indicates a cancel policy exists. If false, no cancel policy exists. Typically this indicator is used when details are not being sent.

Reservation - CancelPenalty

Name Type Description
PenaltyDescription complex Text description of the penalty in a given language. Maximum elements: 9

Reservation - PenaltyDescription

Name Type Description
Text formattedTextTextType Formatted text content.

Cancel

Message used to indicate to the hotel supplier that a given reservation should be cancelled.

SOAPAction OTA Name Message Structure
cancel Cancel OTA_CancelRQ

Request

<?xml version="1.0" encoding="UTF-8"?>
<Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">
  <Header xmlns="http://schemas.xmlsoap.org/soap/envelope/">
    <authentication xmlns="http://www.concur.com/webservice/auth">
      <userid>user</userid>
      <password>password</password>
    </authentication>
  </Header>
  <Body xmlns="http://schemas.xmlsoap.org/soap/envelope/">
    <OTA_CancelRQ xmlns="http://www.opentravel.org/OTA/2003/05" EchoToken="test_request_id" Version="3"
                  PrimaryLangID="en" AltLangID="en" CancelType="Cancel">
      <POS>
        <Source ISOCurrency="USD"></Source>
      </POS>
      <UniqueID Type="14" ID="11112222"></UniqueID>
    </OTA_CancelRQ>
  </Body>
</Envelope>

OTA_CancelRQ

Name Type Description
UniqueID `complex Required Element to hold the type and the ID of the reservation to be cancelled.

UniqueID

Name Type Description
Type string Required UniqueID with Type=14 identifies the reservation to cancel.
ID stringLength1to32 Required A unique identifying value assigned by the creating system.

Response

The maximum allowed size of OTA_CancelRS is 150 KB. Any response that exceeds this limit shall be dropped.

<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <SOAP-ENV:Header xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"/>
  <soap:Body>
    <OTA_CancelRS xmlns="http://www.opentravel.org/OTA/2003/05" Version="3" Status="Cancelled">
      <Success/>
      <UniqueID ID="11112222" Type="14"/>
      <UniqueID ID="12122" Type="15"/>
    </OTA_CancelRS>
  </soap:Body>
</soap:Envelope>

OTA_CancelRS

Name Type Description
Status string Required Supported values: Cancelled, Unsuccessful
Success `successType An element that is not intended to contain any data. The mere presence of a success element within the response message indicates that the incoming request message was processed successfully.
UniqueID string Required See UniqueID above. SAP Concur expects two (2) UniqueIDs to be returned in the response. The first with an Type of 14 containing the original reservation number, and the second Type of 15 containing a confirmation number. Both elements are mandatory.

Appendix

./media/image1.png

Request

<?xml version="1.0" encoding="UTF-8"?>
<Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">
  <Header xmlns="http://schemas.xmlsoap.org/soap/envelope/">
    <authentication xmlns="http://www.concur.com/webservice/auth">
      <userid>testLogin123</userid>
      <password>txxxxxxxxxxxx;</password>
    </authentication>
  </Header>
  <Body xmlns="http://schemas.xmlsoap.org/soap/envelope/">
    <OTA_HotelSearchRQ xmlns="http://www.opentravel.org/OTA/2003/05"
                       EchoToken="5ADE581A-8A7C-4DA5-A67B-EED4E58A80E2"
                       Version="4" PrimaryLangID="en" AltLangID="en" MaxResponses="100">
      <POS>
        <Source ISOCurrency="USD"></Source>
      </POS>
      <Criteria>
        <Criterion>
          <Position Latitude="52.559720" Longitude="13.287780"></Position>
          <RefPoint></RefPoint>
          <Radius Distance="5" DistanceMax="30" UnitOfMeasureCode="1"></Radius>
          <StayDateRange Start="2018-02-12" End="2018-02-13"></StayDateRange>
        </Criterion>
      </Criteria>
    </OTA_HotelSearchRQ>
  </Body>
</Envelope>

Response

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <SOAP-ENV:Header xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"/>
  <soap:Body>
    <OTA_HotelSearchRS xmlns="http://www.opentravel.org/OTA/2003/05" xmlns:ns2="http://www.concur.com/webservice/auth" AltLangID="fr" EchoToken="FC6F5CDE-2D55-49A4-AE22-056AF980ADF4" PrimaryLangID="fr" Version="4">
      <Success/>
      <Properties>
        <Property ChainName="Appart City" HotelCode="399671" HotelName="Appart'City Aix en Provence - La Duranne Residence de Tourisme">
          <Position Latitude="43.49205" Longitude="5.351965"/>
          <Address>
            <AddressLine>300 avenue du Grand Vallat</AddressLine>
            <CityName>Les Milles</CityName>
            <PostalCode>13290</PostalCode>
            <CountryName Code="FR">French Republic France</CountryName>
          </Address>
          <Award Rating="2"/>
          <HotelAmenity Code="68"/>
          <HotelAmenity Code="198"/>
          <HotelAmenity Code="71"/>
          <HotelAmenity Code="101"/>
          <HotelAmenity Code="33"/>
          <Policy CheckInTime="14:00:00" CheckOutTime="12:00:00"/>
          <TPA_Extensions>
            <HotelPreference>not_preferred</HotelPreference>
            <TPA_HotelPreviewImageURI>
              <URL>https://foto.hrsstatic.com/fotos/1/3/75/75/80/FFFFFF/http%3A%2F%2Ffoto-origin.hrsstatic.com%2Ffoto%2F3%2F9%2F9%2F6%2Fteaser_399671.jpg/v1M9Y02mJkgafy7d97qkhw%3D%3D/128%2C85/6/AppartCity_Aix_en_Provence_La_Duranne_Residence_de_Tourisme-Les_Milles_Aix-en-Provence-Exterior_view-3-399671.jpg</URL>
            </TPA_HotelPreviewImageURI>
          </TPA_Extensions>
        </Property>
        <Property>
          ... and another properties follow here for all the returned hotels
        </Property>
      </Properties>
    </OTA_HotelSearchRS>
  </soap:Body>
</soap:Envelope>

Availability

The initial Search request (see above) is followed up by an multi-property Availability request. In the example request below Concur requests the availability for 13 properties. This could because the initial search only yielded 13 properties or the configuration per vendor is set to request availability for a maximum of 13 properties.

Request

<?xml version="1.0" encoding="UTF-8"?>
<Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">
  <Header xmlns="http://schemas.xmlsoap.org/soap/envelope/">
    <authentication xmlns="http://www.concur.com/webservice/auth">
      <userid>testLogin123</userid>
      <password>txxxxxxxxxxxx;</password>
    </authentication>
  </Header>
  <Body xmlns="http://schemas.xmlsoap.org/soap/envelope/">
    <OTA_HotelAvailRQ xmlns="http://www.opentravel.org/OTA/2003/05"
                      EchoToken="5ADE581A-8A7C-4DA5-A67B-EED4E58A80E2"
                      Version="5" PrimaryLangID="en" AltLangID="en">
      <POS>
        <Source ISOCurrency="USD"></Source>
      </POS>
      <AvailRequestSegments>
        <AvailRequestSegment>
          <HotelSearchCriteria>
            <Criterion>
              <HotelRef ChainCode="ZZ" HotelCode="50709"></HotelRef>
            </Criterion>
            <Criterion>
              <HotelRef ChainCode="ZZ" HotelCode="468159"></HotelRef>
            </Criterion>
            <Criterion>
              <HotelRef ChainCode="ZZ" HotelCode="584875"></HotelRef>
            </Criterion>
            <Criterion>
              <HotelRef ChainCode="ZZ" HotelCode="765336"></HotelRef>
            </Criterion>
            <Criterion>
              <HotelRef ChainCode="ZZ" HotelCode="70346"></HotelRef>
            </Criterion>
            <Criterion>
              <HotelRef ChainCode="ZZ" HotelCode="52198"></HotelRef>
            </Criterion>
            <Criterion>
              <HotelRef ChainCode="ZZ" HotelCode="697768"></HotelRef>
            </Criterion>
            <Criterion>
              <HotelRef ChainCode="ZZ" HotelCode="14411"></HotelRef>
            </Criterion>
            <Criterion>
              <HotelRef ChainCode="ZZ" HotelCode="436533"></HotelRef>
            </Criterion>
            <Criterion>
              <HotelRef ChainCode="ZZ" HotelCode="459980"></HotelRef>
            </Criterion>
            <Criterion>
              <HotelRef ChainCode="ZZ" HotelCode="419430"></HotelRef>
            </Criterion>
            <Criterion>
              <HotelRef ChainCode="ZZ" HotelCode="92103"></HotelRef>
            </Criterion>
            <Criterion>
              <HotelRef ChainCode="ZZ" HotelCode="252272"></HotelRef>
            </Criterion>
          </HotelSearchCriteria>
          <StayDateRange Start="2018-02-12" End="2018-02-13"></StayDateRange>
          <RoomStayCandidates>
            <RoomStayCandidate>
              <GuestCounts>
                <GuestCount AgeQualifyingCode="10" Count="1"></GuestCount>
              </GuestCounts>
            </RoomStayCandidate>
          </RoomStayCandidates>
        </AvailRequestSegment>
      </AvailRequestSegments>
    </OTA_HotelAvailRQ>
  </Body>
</Envelope>

Response

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <SOAP-ENV:Header xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"/>
  <soap:Body>
    <OTA_HotelAvailRS xmlns="http://www.opentravel.org/OTA/2003/05" xmlns:ns2="http://www.concur.com/webservice/auth" AltLangID="fr" EchoToken="FC6F5CDE-2D55-49A4-AE22-056AF980ADF4" PrimaryLangID="fr" Version="5">
      <Success/>
      <RoomStays>
        <RoomStay>
          <RoomTypes>
            <RoomType RoomID="b3da298f">
              <RoomDescription>
                <Text>La chambre standard est équipée de douche/WC ou de baignoire/WC.</Text>
              </RoomDescription>
              <Amenities>
                <Amenity ExistsCode="1" RoomAmenity="55"/>
                <Amenity ExistsCode="1" RoomAmenity="56"/>
                <Amenity ExistsCode="1" RoomAmenity="4"/>
                <Amenity ExistsCode="1" RoomAmenity="28"/>
                <Amenity ExistsCode="1" RoomAmenity="210"/>
                <Amenity ExistsCode="1" RoomAmenity="92"/>
                <Amenity ExistsCode="1" RoomAmenity="2"/>
                <Amenity ExistsCode="1" RoomAmenity="126"/>
                <Amenity ExistsCode="1" RoomAmenity="19"/>
                <Amenity ExistsCode="1" RoomAmenity="13"/>
                <Amenity ExistsCode="1" RoomAmenity="96"/>
                <Amenity ExistsCode="1" RoomAmenity="50"/>
                <Amenity ExistsCode="1" RoomAmenity="69"/>
                <Amenity ExistsCode="1" RoomAmenity="107"/>
                <Amenity ExistsCode="1" RoomAmenity="10"/>
              </Amenities>
            </RoomType>
          </RoomTypes>
          <RatePlans>
            <RatePlan AvailabilityStatus="AvailableForSale" PrepaidIndicator="false" RatePlanID="TOGG3BU">
              <Guarantee GuaranteeType="GuaranteeRequired">
                <Deadline AbsoluteDeadline="2019-05-08T23:59:59"/>
              </Guarantee>
              <CancelPenalties>
                <CancelPenalty NonRefundable="false">
                  <Deadline AbsoluteDeadline="2019-05-08T23:59:59" OffsetDropTime="BeforeArrival" OffsetTimeUnit="Day"
                            OffsetUnitMultiplier="14"/>
                </CancelPenalty>
              </CancelPenalties>
              <MealsIncluded Breakfast="false" Dinner="false" Lunch="false"/>
            </RatePlan>
          </RatePlans>
          <RoomRates>
            <RoomRate RatePlanID="TOGG3BU" RoomID="b3da298f">
              <Rates>
                <Rate ChargeType="18" GuaranteedInd="true" NumberOfUnits="1" RateTimeUnit="FullDuration"
                      RoomPricingType="Per stay" UnitMultiplier="1">
                  <PaymentPolicies>
                    <GuaranteePayment>
                      <AcceptedPayments>
                        <AcceptedPayment>
                          <PaymentCard>
                            <CardType>VISA</CardType>
                          </PaymentCard>
                        </AcceptedPayment>
                      </AcceptedPayments>
                    </GuaranteePayment>
                    <GuaranteePayment>
                      <AcceptedPayments>
                        <AcceptedPayment>
                          <PaymentCard>
                            <CardType>Mastercard</CardType>
                          </PaymentCard>
                        </AcceptedPayment>
                      </AcceptedPayments>
                    </GuaranteePayment>
                  </PaymentPolicies>
                  <Total AmountAfterTax="161.10" AmountBeforeTax="152.70" CurrencyCode="EUR" DecimalPlaces="2"/>
                  <RateDescription>
                    <Text>Tarif promotionnel</Text>
                    <Text>Gratuit pour les clients HRS: Quotidien gratuit, Parking attenant à l'hôtel</Text>
                  </RateDescription>
                </Rate>
              </Rates>
            </RoomRate>
          </RoomRates>
          <GuestCounts>
            <GuestCount Count="1"/>
          </GuestCounts>
          <TimeSpan End="2019-05-23" Start="2019-05-22"/>
          <BasicPropertyInfo HotelCode="36151" HotelName="Château de la Pioline">
            <Address>
              <AddressLine>260 Rue Guillaume du Vair</AddressLine>
              <CityName>AIX EN PROVENCE</CityName>
              <PostalCode>13546</PostalCode>
              <CountryName Code="FR">French Republic France</CountryName>
            </Address>
            <ContactNumbers>
              <ContactNumber PhoneNumber="33442522727"/>
            </ContactNumbers>
          </BasicPropertyInfo>
        </RoomStay>
        <RoomStay>
          <RoomTypes>
            <RoomType RoomID="f7631619">
              <RoomDescription>
                <Text>La chambre standard est équipée de douche/WC ou de baignoire/WC.</Text>
              </RoomDescription>
              <Amenities>
                <Amenity ExistsCode="1" RoomAmenity="55"/>
                <Amenity ExistsCode="1" RoomAmenity="56"/>
                <Amenity ExistsCode="1" RoomAmenity="4"/>
                <Amenity ExistsCode="1" RoomAmenity="28"/>
                <Amenity ExistsCode="1" RoomAmenity="210"/>
                <Amenity ExistsCode="1" RoomAmenity="92"/>
                <Amenity ExistsCode="1" RoomAmenity="2"/>
                <Amenity ExistsCode="1" RoomAmenity="126"/>
                <Amenity ExistsCode="1" RoomAmenity="19"/>
                <Amenity ExistsCode="1" RoomAmenity="13"/>
                <Amenity ExistsCode="1" RoomAmenity="96"/>
                <Amenity ExistsCode="1" RoomAmenity="50"/>
                <Amenity ExistsCode="1" RoomAmenity="69"/>
                <Amenity ExistsCode="1" RoomAmenity="107"/>
                <Amenity ExistsCode="1" RoomAmenity="10"/>
              </Amenities>
            </RoomType>
          </RoomTypes>
          <RatePlans>
            <RatePlan AvailabilityStatus="AvailableForSale" PrepaidIndicator="false" RatePlanID="MB4YV34">
              <Guarantee GuaranteeType="Deposit"/>
              <CancelPenalties>
                <CancelPenalty NonRefundable="true">
                  <Deadline AbsoluteDeadline="2019-04-15T12:51:47"/>
                </CancelPenalty>
              </CancelPenalties>
              <MealsIncluded Breakfast="false" Dinner="false" Lunch="false"/>
            </RatePlan>
          </RatePlans>
          <RoomRates>
            <RoomRate RatePlanID="MB4YV34" RoomID="f7631619">
              <Rates>
                <Rate ChargeType="18" GuaranteedInd="true" NumberOfUnits="1" RateTimeUnit="FullDuration"
                      RoomPricingType="Per stay" UnitMultiplier="1">
                  <PaymentPolicies>
                    <GuaranteePayment>
                      <AcceptedPayments>
                        <AcceptedPayment>
                          <PaymentCard>
                            <CardType>VISA</CardType>
                          </PaymentCard>
                        </AcceptedPayment>
                      </AcceptedPayments>
                    </GuaranteePayment>
                    <GuaranteePayment>
                      <AcceptedPayments>
                        <AcceptedPayment>
                          <PaymentCard>
                            <CardType>Mastercard</CardType>
                          </PaymentCard>
                        </AcceptedPayment>
                      </AcceptedPayments>
                    </GuaranteePayment>
                  </PaymentPolicies>
                  <Total AmountAfterTax="149.00" AmountBeforeTax="141.23" CurrencyCode="EUR" DecimalPlaces="2"/>
                  <RateDescription>
                    <Text>Hot Deal</Text>
                    <Text>Gratuit pour les clients HRS: Quotidien gratuit, Parking attenant à l'hôtel</Text>
                  </RateDescription>
                </Rate>
              </Rates>
            </RoomRate>
          </RoomRates>
          <GuestCounts>
            <GuestCount Count="1"/>
          </GuestCounts>
          <TimeSpan End="2019-05-23" Start="2019-05-22"/>
          <BasicPropertyInfo HotelCode="36151" HotelName="Château de la Pioline">
            <Address>
              <AddressLine>260 Rue Guillaume du Vair</AddressLine>
              <CityName>AIX EN PROVENCE</CityName>
              <PostalCode>13546</PostalCode>
              <CountryName Code="FR">French Republic France</CountryName>
            </Address>
            <ContactNumbers>
              <ContactNumber PhoneNumber="33442522727"/>
            </ContactNumbers>
          </BasicPropertyInfo>
        </RoomStay>
        <RoomStay>
          ... and another RoomStay nodes follow here for all the returned rooms for all the hotels (properties) per
          Availability request
        </RoomStay>
      </RoomStays>
    </OTA_HotelAvailRS>
  </soap:Body>
</soap:Envelope>

Search results displayed

Search results page displaying hotels, based on Search response, and their rates, based on Availability response:

./media/image1.png

WIth Availability response also cancellation information comes which can be displayed in separate popup:

./media/image1.png

Hotel Description

./media/image1.png

Request

<?xml version="1.0" encoding="UTF-8"?>
<Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">
  <Header xmlns="http://schemas.xmlsoap.org/soap/envelope/">
    <authentication xmlns="http://www.concur.com/webservice/auth">
      <userid>testLogin123</userid>
      <password>txxxxxxxxxxxx;</password>
    </authentication>
  </Header>
  <Body xmlns="http://schemas.xmlsoap.org/soap/envelope/">
    <OTA_HotelDescriptiveInfoRQ xmlns="http://www.opentravel.org/OTA/2003/05"
                                EchoToken="A78F3641-8674-43F9-B58C-AD928D1A75D9"
                                Version="3" PrimaryLangID="en" AltLangID="en">
      <POS>
        <Source ISOCurrency="USD"></Source>
      </POS>
      <HotelDescriptiveInfos>
        <HotelDescriptiveInfo ChainCode="ZZ" HotelCode="419430"></HotelDescriptiveInfo>
      </HotelDescriptiveInfos>
    </OTA_HotelDescriptiveInfoRQ>
  </Body>
</Envelope>

Response

<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <SOAP-ENV:Header xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"/>
  <soap:Body>
    <OTA_HotelDescriptiveInfoRS xmlns="http://www.opentravel.org/OTA/2003/05"
                                xmlns:ns2="http://www.concur.com/webservice/auth">
      <Success/>
      <HotelDescriptiveContents>
        <HotelDescriptiveContent ChainCode="ZZ" HotelCode="419430" HotelName="Courtyard Prague Airport">
          <HotelInfo>
            <Descriptions>
              <DescriptiveText>Prague (PRG): The Europort building which housed the hotel is located in front of the
                arrivial and departure halls at Prague-ruzyne Airport. The hotel will have direct access to the
                airport’s infrastructure and offer connections to both the walkway and transporation routes. The
                conveniently located Courtyard Prague Airport provides its guests upscale accommodation outside the
                buzzing city centre. Kept in a cosy elegant design, the comfortable rooms are fitted with coffee and tea
                maker and nice sitting and working area. The magnificent atrium with its modern structure and nice
                garden invites to stay and relax. Directly situated at Prague’s international airport, the hotel is
                about 16 kilometres from the city centre and the historic castle. In the nearby surroundings, guests can
                enjoy horseback riding, biking or kayaking. Oléo Pazzo Mediterranean Bistro is a contemporary restaurant
                decorated in warm and coulourful style with a show kitchen and a trendy bar. Other features are a
                fitness,a business center,meeting rooms.
              </DescriptiveText>
            </Descriptions>
          </HotelInfo>
          <MultimediaDescriptions>
            <MultimediaDescription>
              <ImageItems>
                <ImageItem>
                  <ImageFormat>
                    <URL>http://iut-foto-origin.hrsstatic.com/foto/3/8/9/8/389886/389886_fi_451616.jpg</URL>
                  </ImageFormat>
                </ImageItem>
                <ImageItem>
                  <ImageFormat>
                    <URL>http://iut-foto-origin.hrsstatic.com/foto/3/8/9/8/389886/389886_u_6302064.jpg</URL>
                  </ImageFormat>
                </ImageItem>
                <ImageItem>
                  <ImageFormat>
                    <URL>http://iut-foto-origin.hrsstatic.com/foto/3/8/9/8/389886/389886_u_451896.jpg</URL>
                  </ImageFormat>
                </ImageItem>
              </ImageItems>
            </MultimediaDescription>
          </MultimediaDescriptions>
          <TPA_Extensions>
            <Description Name="First Description">
              <Text>First line of first description.</Text>
              <Text>Second line of first description.</Text>
            </Description>
            <Description>
              <Text>Second description without name.</Text>
            </Description>
          </TPA_Extensions>
        </HotelDescriptiveContent>
      </HotelDescriptiveContents>
    </OTA_HotelDescriptiveInfoRS>
  </soap:Body>
</soap:Envelope>

Hotel Details displayed

./media/image1.png

Reservation

./media/image1.png ./media/image1.png

./media/image1.png ./media/image1.png

Request

<?xml version="1.0" encoding="UTF-8"?>
<Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">
  <Header xmlns="http://schemas.xmlsoap.org/soap/envelope/">
    <authentication xmlns="http://www.concur.com/webservice/auth">
      <userid>testLogin123</userid>
      <password>txxxxxxxxxxxx;</password>
    </authentication>
  </Header>
  <Body xmlns="http://schemas.xmlsoap.org/soap/envelope/">
    <OTA_HotelResRQ xmlns="http://www.opentravel.org/OTA/2003/05"
                    EchoToken="6C85DDBD-EB62-444D-B2C3-F59BDF65BE98"
                    Version="6" PrimaryLangID="en" AltLangID="en">
      <POS>
        <Source ISOCurrency="USD"></Source>
      </POS>
      <HotelReservations>
        <HotelReservation>
          <RoomStays>
            <RoomStay>
              <RatePlans>
                <RatePlan RatePlanID="XNFYP4I">
                  <Guarantee GuaranteeType="CC/DC/Voucher">
                    <GuaranteesAccepted>
                      <GuaranteeAccepted>
                        <PaymentCard CardCode="VI" ExpireDate="1220">
                          <CardType Code="VI">VISA</CardType>
                          <CardHolderName>HOTELSERVICEAMADEUS TESTUSERMOCK</CardHolderName>
                        </PaymentCard>
                      </GuaranteeAccepted>
                    </GuaranteesAccepted>
                  </Guarantee>
                </RatePlan>
              </RatePlans>
              <TimeSpan Start="2018-02-12" End="2018-02-13"></TimeSpan>
              <BasicPropertyInfo HotelCode="419430"></BasicPropertyInfo>
            </RoomStay>
          </RoomStays>
          <ResGuests>
            <ResGuest>
              <Profiles>
                <ProfileInfo>
                  <Profile>
                    <Customer Gender="Unknown">
                      <PersonName Language="en">
                        <GivenName>HOTELSERVICEAMADEUS</GivenName>
                        <Surname>TESTUSERMOCK</Surname>
                      </PersonName>
                      <Telephone PhoneNumber="3141011001"></Telephone>
                      <Email>hrs_hs2_amadeus_mock@concurautm3.com</Email>
                      <Address>
                        <AddressLine>123 Sesame St.</AddressLine>
                        <CityName>Alexandria</CityName>
                        <PostalCode>22314</PostalCode>
                        <StateProv></StateProv>
                        <CountryName Code="US">USA</CountryName>
                      </Address>
                      <CitizenCountryName Code="US"></CitizenCountryName>
                    </Customer>
                    <CompanyInfo>
                      <CompanyName>CONCURTECH</CompanyName>
                    </CompanyInfo>
                  </Profile>
                </ProfileInfo>
              </Profiles>
              <GuestCounts>
                <GuestCount Count="1"></GuestCount>
              </GuestCounts>
            </ResGuest>
          </ResGuests>
        </HotelReservation>
      </HotelReservations>
    </OTA_HotelResRQ>
  </Body>
</Envelope>

Response

<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <SOAP-ENV:Header xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"/>
  <soap:Body>
    <OTA_HotelResRS xmlns="http://www.opentravel.org/OTA/2003/05"
                    xmlns:ns2="http://www.concur.com/webservice/auth"
                    ResResponseType="Reserved">
      <Success/>
      <HotelReservations>
        <HotelReservation>
          <UniqueID ID="88618333"/>
          <RoomStays>
            <RoomStay>
              <RatePlans>
                <RatePlan RatePlanID="EZ57LL7">
                  <CancelPenalties CancelPolicyIndicator="true">
                    <CancelPenalty>
                      <PenaltyDescription>
                        <Text>test cancel policy 1</Text>
                      </PenaltyDescription>
                    </CancelPenalty>
                    <CancelPenalty>
                      <Deadline AbsoluteDeadline="2018-02-22T18:00"/>
                    </CancelPenalty>
                  </CancelPenalties>
                </RatePlan>
              </RatePlans>
              <RoomRates>
                <RoomRate>
                  <Rates>
                    <Rate RoomPricingType="Per stay">
                      <PaymentPolicies>
                        <GuaranteePayment>
                          <AcceptedPayments>
                            <AcceptedPayment>
                              <PaymentCard CardCode="VI"/>
                            </AcceptedPayment>
                          </AcceptedPayments>
                        </GuaranteePayment>
                        <GuaranteePayment>
                          <AcceptedPayments>
                            <AcceptedPayment>
                              <PaymentCard CardCode="MC"/>
                            </AcceptedPayment>
                          </AcceptedPayments>
                        </GuaranteePayment>
                        <GuaranteePayment>
                          <AcceptedPayments>
                            <AcceptedPayment>
                              <PaymentCard CardCode="CA"/>
                            </AcceptedPayment>
                          </AcceptedPayments>
                        </GuaranteePayment>
                        <GuaranteePayment>
                          <AcceptedPayments>
                            <AcceptedPayment>
                              <PaymentCard CardCode="IK"/>
                            </AcceptedPayment>
                          </AcceptedPayments>
                        </GuaranteePayment>
                        <GuaranteePayment>
                          <AcceptedPayments>
                            <AcceptedPayment>
                              <PaymentCard CardCode="AX"/>
                            </AcceptedPayment>
                          </AcceptedPayments>
                        </GuaranteePayment>
                      </PaymentPolicies>
                      <Total AmountAfterTax="85.00" AmountBeforeTax="85.00" CurrencyCode="EUR"/>
                    </Rate>
                  </Rates>
                </RoomRate>
              </RoomRates>
              <TimeSpan End="2018-02-23" Start="2018-02-22"/>
              <BasicPropertyInfo HotelCode="50709" HotelName="Alexander Plaza">
                <Address>
                  <AddressLine>Rosenstr. 1</AddressLine>
                  <CityName>Berlin</CityName>
                  <CountryName Code="DEU">Federal Republic of Germany</CountryName>
                  <StateProv StateCode="BE">Berlin disctrict</StateProv>
                  <PostalCode>BE123</PostalCode>
                </Address>
                <ContactNumbers>
                  <ContactNumber PhoneNumber="3024001722"/>
                </ContactNumbers>
              </BasicPropertyInfo>
            </RoomStay>
          </RoomStays>
          <ResGuests>
            <ResGuest>
              <Profiles>
                <ProfileInfo>
                  <Profile>
                    <Customer>
                      <PersonName>
                        <GivenName>TESTER</GivenName>
                        <Surname>Testovic</Surname>
                      </PersonName>
                    </Customer>
                  </Profile>
                </ProfileInfo>
              </Profiles>
            </ResGuest>
          </ResGuests>
          <ResGlobalInfo>
            <Comments>
              <Comment Name="Comment 1">
                <Text>First line of Comment 1.</Text>
                <Text>Second line of Comment 1.</Text>
              </Comment>
              <Comment>
                <Text>First line of Comment 2 without name.</Text>
              </Comment>
            </Comments>
          </ResGlobalInfo>
        </HotelReservation>
      </HotelReservations>
    </OTA_HotelResRS>
  </soap:Body>
</soap:Envelope>

Read

./media/image1.png ./media/image1.png ./media/image1.png

Request

<?xml version="1.0" encoding="UTF-8"?>
<Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">
  <Header xmlns="http://schemas.xmlsoap.org/soap/envelope/">
    <authentication xmlns="http://www.concur.com/webservice/auth">
      <userid>testLogin123</userid>
      <password>txxxxxxxxxxxx;</password>
    </authentication>
  </Header>
  <Body xmlns="http://schemas.xmlsoap.org/soap/envelope/">
    <OTA_ReadRQ xmlns="http://www.opentravel.org/OTA/2003/05"
                EchoToken="4E1B8BF4-ACBD-4709-9FCC-B59EB2550086"
                Version="5.002" PrimaryLangID="en" AltLangID="en">
      <POS>
        <Source ISOCurrency="USD"></Source>
      </POS>
      <UniqueID Type="14" ID="88618333"></UniqueID>
    </OTA_ReadRQ>
  </Body>
</Envelope>

Response

<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <SOAP-ENV:Header xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"/>
  <soap:Body>
    <OTA_HotelResRS xmlns="http://www.opentravel.org/OTA/2003/05"
                    xmlns:ns2="http://www.concur.com/webservice/auth"
                    ResResponseType="Reserved">
      <Success/>
      <HotelReservations>
        <HotelReservation>
          <UniqueID ID="88621190"/>
          <RoomStays>
            <RoomStay>
              <RatePlans>
                <RatePlan RatePlanID="P4PGI5Q">
                  <CancelPenalties CancelPolicyIndicator="true">
                    <CancelPenalty>
                      <PenaltyDescription>
                        <Text>test cancel policy 1</Text>
                      </PenaltyDescription>
                    </CancelPenalty>
                    <CancelPenalty>
                      <PenaltyDescription>
                        <Text>test cancel policy 2</Text>
                      </PenaltyDescription>
                      <PenaltyDescription>
                        <Text>test cancel policy 3</Text>
                      </PenaltyDescription>
                    </CancelPenalty>
                    <CancelPenalty>
                      <Deadline AbsoluteDeadline="2018-02-22T18:00"/>
                    </CancelPenalty>
                  </CancelPenalties>
                </RatePlan>
              </RatePlans>
              <RoomRates>
                <RoomRate>
                  <Rates>
                    <Rate RoomPricingType="Per stay">
                      <PaymentPolicies>
                        <GuaranteePayment>
                          <AcceptedPayments>
                            <AcceptedPayment>
                              <PaymentCard CardCode="VI"/>
                            </AcceptedPayment>
                          </AcceptedPayments>
                        </GuaranteePayment>
                        <GuaranteePayment>
                          <AcceptedPayments>
                            <AcceptedPayment>
                              <PaymentCard CardCode="MC"/>
                            </AcceptedPayment>
                          </AcceptedPayments>
                        </GuaranteePayment>
                        <GuaranteePayment>
                          <AcceptedPayments>
                            <AcceptedPayment>
                              <PaymentCard CardCode="CA"/>
                            </AcceptedPayment>
                          </AcceptedPayments>
                        </GuaranteePayment>
                        <GuaranteePayment>
                          <AcceptedPayments>
                            <AcceptedPayment>
                              <PaymentCard CardCode="IK"/>
                            </AcceptedPayment>
                          </AcceptedPayments>
                        </GuaranteePayment>
                        <GuaranteePayment>
                          <AcceptedPayments>
                            <AcceptedPayment>
                              <PaymentCard CardCode="AX"/>
                            </AcceptedPayment>
                          </AcceptedPayments>
                        </GuaranteePayment>
                      </PaymentPolicies>
                      <Total AmountAfterTax="208.95" AmountBeforeTax="208.95" CurrencyCode="EUR"/>
                    </Rate>
                  </Rates>
                </RoomRate>
              </RoomRates>
              <TimeSpan End="2018-02-23" Start="2018-02-22"/>
              <BasicPropertyInfo ChainCode="1609" HotelCode="10517" HotelName="Radisson Blu Hotel">
                <Address>
                  <AddressLine>Karl-Liebknecht-Str. 3</AddressLine>
                  <CityName>Berlin</CityName>
                  <CountryName Code="DEU">Federal Republic of Germany</CountryName>
                  <StateProv StateCode="BE">Berlin disctrict</StateProv>
                  <PostalCode>BE123</PostalCode>
                </Address>
                <ContactNumbers>
                  <ContactNumber PhoneNumber="30238280"/>
                </ContactNumbers>
              </BasicPropertyInfo>
            </RoomStay>
          </RoomStays>
          <ResGuests>
            <ResGuest>
              <Profiles>
                <ProfileInfo>
                  <Profile>
                    <Customer>
                      <PersonName>
                        <GivenName>TESTER</GivenName>
                        <Surname>Testovic</Surname>
                      </PersonName>
                    </Customer>
                  </Profile>
                </ProfileInfo>
              </Profiles>
            </ResGuest>
          </ResGuests>
          <ResGlobalInfo>
            <Comments>
              <Comment Name="Comment 1">
                <Text>First line of Comment 1.</Text>
                <Text>Second line of Comment 1.</Text>
              </Comment>
              <Comment>
                <Text>First line of Comment 2 without name.</Text>
              </Comment>
            </Comments>
          </ResGlobalInfo>
        </HotelReservation>
      </HotelReservations>
    </OTA_HotelResRS>
  </soap:Body>
</soap:Envelope>

Itinerary displayed

./media/image1.png ./media/image1.png

Cancel

./media/image1.png ./media/image1.png

Request

<Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">
  <Header xmlns="http://schemas.xmlsoap.org/soap/envelope/">
    <authentication xmlns="http://www.concur.com/webservice/auth">
      <userid>testLogin123</userid>
      <password>txxxxxxxxxxxx;</password>
    </authentication>
  </Header>
  <Body xmlns="http://schemas.xmlsoap.org/soap/envelope/">
    <OTA_CancelRQ xmlns="http://www.opentravel.org/OTA/2003/05" CancelType="Cancel"
                  EchoToken="2186EB84-23D9-4977-B8A5-B5083C8DE228"
                  Version="3" PrimaryLangID="en" AltLangID="en">
      <POS>
        <Source ISOCurrency="USD"></Source>
      </POS>
      <UniqueID Type="14" ID="88618333"></UniqueID>
    </OTA_CancelRQ>
  </Body>
</Envelope>

Response

<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <SOAP-ENV:Header xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"/>
  <soap:Body>
    <OTA_CancelRS xmlns="http://www.opentravel.org/OTA/2003/05"
                  xmlns:ns2="http://www.concur.com/webservice/auth"
                  Status="Cancelled">
      <Success/>
      <UniqueID ID="88618333" Type="14"/>
      <UniqueID ID="27607" Type="15"/>
    </OTA_CancelRS>
  </soap:Body>
</soap:Envelope>

./media/image1.png ./media/image1.png

XSD schema

Current xsd schema for Hotel Service 2

HotelService2.xsd

Expense

Allocations

The SAP Concur Allocations API allows for the retrieval of allocation information as it relates to a Report ID, Entry ID, or Itemization ID. Using this API allows for an in-depth review of Expense Report Data and how that data has been allocated in SAP Concur. The Allocations API allows for the programmatic gathering of details on how the expense report data was allocated by the report owner, making it ideal for Data Gathering, Expense Reporting, and Validations.

Version

3.0

Retrieve All Allocations Per Entry or Report

GET /api/v3.0/expense/allocations

Parameters

Name Type Format Description
limit Int32 query The number of records to return. The default is 25 and the maximum is 100.
offset string query The starting point of the next set of results, after the limit specified in the limit field has been reached.
reportID string query The unique identifier for the report as it appears in the Concur Expense UI. Format: A variable-length string. Maximum length: 32 characters.
entryID string query The unique identifier for the expense entry.
itemizationID string query The unique identifier for the expense itemization.

Note: userId is not a supported query string parameter for this API.

Request URL

https://www.concursolutions.com/api/v3.0/expense/allocations?limit=10

JSON Example of a Successful Response

{
  "Items": [
    {
      "EntryID": "gWidFO7ikXSy7gHnNngC12jkL7khMiREv4g",
      "Percentage": "100.00000000",
      "IsPercentEdited": false,
      "IsHidden": true,
      "AccountCode1": "1",
      "AccountCode2": null,
      "Custom1": null,
      "Custom2": null,
      "Custom3": null,
      "Custom4": null,
      "Custom5": null,
      "Custom6": null,
      "Custom7": null,
      "Custom8": null,
      "Custom9": null,
      "Custom10": null,
      "Custom11": null,
      "Custom12": null,
      "Custom13": null,
      "Custom14": null,
      "Custom15": null,
      "Custom16": null,
      "Custom17": null,
      "Custom18": null,
      "Custom19": null,
      "Custom20": null,
      "ID": "gWmudeHM8AuFikny3Hrpz$s2gaNvc0E7Xfyw",
      "URI": "https://www.concursolutions.com/api/v3.0/expense/allocations/gWmudeHM8AuFikny3Hrpz$s2gaNvc0E7Xfyw"
    },
    {
      "EntryID": "gWidFO7ikXSy41$smPkwdC5cL1aku$pSgc$p4g",
      "Percentage": "100.00000000",
      "IsPercentEdited": false,
      "IsHidden": true,
      "AccountCode1": "1",
      "AccountCode2": null,
      "Custom1": null,
      "Custom2": null,
      "Custom3": null,
      "Custom4": null,
      "Custom5": null,
      "Custom6": null,
      "Custom7": null,
      "Custom8": null,
      "Custom9": null,
      "Custom10": null,
      "Custom11": null,
      "Custom12": null,
      "Custom13": null,
      "Custom14": null,
      "Custom15": null,
      "Custom16": null,
      "Custom17": null,
      "Custom18": null,
      "Custom19": null,
      "Custom20": null,
      "ID": "gWmudeHM8AuFhxez1E72ExJPksvTH0KPPyw",
      "URI": "https://www.concursolutions.com/api/v3.0/expense/allocations/gWmudeHM8AuFhxez1E72ExJPksvTH0KPPyw"
    }
  ]
}

Response

Allocations Schema

Retrieve a Single Allocation by ID

GET /api/v3.0/expense/allocations/{id}

Parameters

Name Type Format Description
id string path Required The unique identifier for the allocation.
user string query The login ID of the user who owns the allocation. The user must have the Web Services Admin role to use this parameter.

Allocations - Schema

Allocations

Name Type Format Description
Items array Allocation The result collection.
NextPage string - The URI of the next page of results, if any.

Allocation

Name Type Format Description
AccountNumber string - The primary accounting code assigned to the expense type associated with this allocation. Typically, expense types have only a primary account code.
AccountCode2 string - The secondary or alternative accounting code assigned to the expense type associated with this allocation.
Custom1 through Custom20 CustomFieldExtension - A custom field associated with the allocation. This field may or may not have data, depending on how Expense is configured. Format: Text field. Maximum length: 64 characters.
EntryID string - The unique identifier for the expense entry.
ID string - The unique identifier of the resource.
IsHidden Boolean - Indicates whether the allocation is hidden. Format: true or false
IsPercentEdited Boolean - Indicates whether the percentage has been edited. Format: true or false
Percentage string - The percentage of the expense that is included in this allocation.
URI string - The URI to the resource.

Custom Field

Name Type Format Description
Code string - For list fields, this is the list item code.
Label string - The label value for the custom field.
ListItemID string - For list fields, this is the list item ID.
Sequence integer - The sequence value for this custom field i.e. the order in which this field appears on the form.
Type string - The custom field type. Possible values: Amount, Boolean, ConnectedList, Date, Integer, List, Number, Text
Value string - The value in the Org Unit or Custom field. For list fields, this is the name of the list item. Maximum length: 48 characters

Request URL

https://www.concursolutions.com/api/v3.0/expense/allocations/gWmudeHM8AuFlD9Py%24p7cwkclNQvGC1JQPyw

JSON Example of a Successful Response

{
  "EntryID": "gWidFO7ikXSy8HdaIfw32sJhcmk76TjD$p4g",
  "Percentage": "100.00000000",
  "IsPercentEdited": false,
  "IsHidden": true,
  "AccountCode1": "1",
  "AccountCode2": null,
  "Custom1": null,
  "Custom2": null,
  "Custom3": null,
  "Custom4": null,
  "Custom5": null,
  "Custom6": null,
  "Custom7": null,
  "Custom8": null,
  "Custom9": null,
  "Custom10": null,
  "Custom11": null,
  "Custom12": null,
  "Custom13": null,
  "Custom14": null,
  "Custom15": null,
  "Custom16": null,
  "Custom17": null,
  "Custom18": null,
  "Custom19": null,
  "Custom20": null,
  "ID": "gWmudeHM8AuFlD9Py$p7cwkclNQvGC1JQPyw",
  "URI": "https://www.concursolutions.com/api/v3.0/expense/allocations/gWmudeHM8AuFlD9Py$p7cwkclNQvGC1JQPyw"
}

Attendee Types v3

The Attendee Type resource represents the type of attendee as configured in Concur.

Version

3.0

Attendee Types v1 (Deprecated)

Retrieve all attendees types

GET  /api/v3.0/expense/attendeetypes/

Parameters

Name Type Format Description
offset string query The starting point of the next set of results, after the limit specified in the limit field has been reached.
limit Int32 query The number of records to return. Default value: 25

Request URL

https://www.concursolutions.com/api/v3.0/expense/attendeetypes?limit=10

JSON example of a successful response

{
  "Items": [
    {
      "Name": "Business Guest",
      "Code": "BUSGUEST",
      "AttendeeFormID": "gWvidmKNPVEaOg$s66rqA62OJVXfvHBMs4sw",
      "DuplicateSearchFields": [
        "Title",
        "Company",
        "OwnerEmpName",
        "FirstName",
        "LastName"
      ],
      "ConnectorID": "",
      "AllowManuallyEnteredAttendees": true,
      "AllowAttendeeCountEditing": true,
      "ID": "gWjUHBxUY4iQLA9KTkbtUD6pc",
      "URI": "https://www.concursolutions.com/api/v3.0/expense/attendeetypes/gWjUHBxUY4iQLA9KTkbtUD6pc"
    },
    {
      "Name": "Healthcare Professional",
      "Code": "HCP",
      "AttendeeFormID": "gWvidmKNPVEH7wO$pDpD9$pk6xVlyJ4EjwIdA",
      "DuplicateSearchFields": [
        "Title",
        "Custom18",
        "ExternalId",
        "FirstName",
        "LastName",
        "Custom7",
        "Custom14",
        "Custom15",
        "Custom16",
        "Custom17",
        "Custom19",
        "Custom8",
        "Custom20"
      ],
      "ConnectorID": "",
      "AllowManuallyEnteredAttendees": true,
      "AllowAttendeeCountEditing": false,
      "ID": "gWjYOjoOorT3dhpHGto5H$poJuoa0m",
      "URI": "https://www.concursolutions.com/api/v3.0/expense/attendeetypes/gWjYOjoOorT3dhpHGto5H$poJuoa0m"
    }
  ]
}

Retrieve attendee types by ID

GET  /api/v3.0/expense/attendeetypes/{id}

Parameters

Name Type Format Description
id string path Required The ID of the attendee type.

Request URL

https://www.concursolutions.com/api/v3.0/expense/attendeetypes/gWjYOjoOorT3dhpHGto5H%24poJuoa0m

JSON example of a successful response

{
  "Name": "Healthcare Professional",
  "Code": "HCP",
  "AttendeeFormID": "gWvidmKNPVEH7wO$pDpD9$pk6xVlyJ4EjwIdA",
  "DuplicateSearchFields": [
    "Title",
    "Custom18",
    "ExternalId",
    "FirstName",
    "LastName",
    "Custom7",
    "Custom14",
    "Custom15",
    "Custom16",
    "Custom17",
    "Custom19",
    "Custom8",
    "Custom20"
  ],
  "ConnectorID": "",
  "AllowManuallyEnteredAttendees": true,
  "AllowAttendeeCountEditing": false,
  "ID": "gWjYOjoOorT3dhpHGto5H$poJuoa0m",
  "URI": "https://www.concursolutions.com/api/v3.0/expense/attendeetypes/gWjYOjoOorT3dhpHGto5H$poJuoa0m"
}

Create a new attendee type

DEPRECATED: 05/19/2016 UNSUPPORTED: 11/19/2016

POST  /api/v3.0/expense/attendeetypes

Parameters

Name Type Format Description
content - body Required The AttendeeType object to create.

Input

Attendee Schema

Response

Attendee Schema

Request URL

https://www.concursolutions.com/api/v3.0/expense/attendeetypes

JSON example of a successful response

{
  "ID": "gWjYOj4JuT5VB$paQnF31149$sKgaM$p",
  "URI": "https://www.concursolutions.com/api/v3.0/expense/attendeetypes/gWjYOj4JuT5VB$paQnF31149$sKgaM$p"
}

Update existing attendee type

PUT  /api/v3.0/expense/attendeetypes/{id}

Parameters

Name Type Format Description
id string path Required The ID of the attendee type.
content - body Required The partial or complete Attendee object to update.

Input

Attendee Schema

Response

Attendee Schema

Request URL

https://www.concursolutions.com/api/v3.0/expense/attendeetypes/gWjYOjoa7Fe0HsTGEk417OCzqUf1A

Delete an attendee type

DEPRECATED: 05/19/2016 UNSUPPORTED: 11/19/2016

DELETE  /api/v3.0/expense/attendeetypes{id}

Parameters

Name Type Format Description
id string path Required The ID of the attendee type to delete

Input

Attendee Schema

Response

Attendee Schema

Request URL

https://www.concursolutions.com/api/v3.0/expense/attendeetypes/gWjYOjomP3Jxp6dFC%24pIg%24sc99nQQ3q

Attendee Type - Schema

Attendee Type

Name Type Format Description
AllowAttendeeCountEditing boolean - Determines whether users are allowed to edit the count for this attendee type. Format: true or false
AllowManuallyEnteredAttendees boolean - Determines whether users are allowed to add attendees for this attendee type. Format: true or false
AttendeeFormID string - The unique identifier for the attendee form for this attendee type.
Code string - A code that indicates the type of attendee. Examples: EMPLOYEE, SPOUSE, BUSGUEST. Maximum length: 40 characters
ConnectorID string - The unique identifier for the Application Connector that is the data source for this attendee type. When this field is empty, the Expense database is the data source.
DuplicateSearchFields Array AttendeeType The list of Attendee field IDs used by the Add Attendee user interface to alert users that the attendee they want to add is a possible duplicate. This parent element has a DuplicateSearchField child element for each field ID.
ID string - The unique identifier of the resource.
Name string - The name for the attendee type. This name must be unique. Maximum length: 40 characters
URI string - The URI to the resource.

Digital Tax Invoices

The Digital Tax Invoice web service allows digital tax invoice validators to view tax invoices and update them with a validation status. This web service currently supports the Comprobante Fiscal Digital (CFD) digital tax invoice format used in Mexico. Other countries may be supported in future releases.

Version

3.0

Retrieve All Digital Tax Invoices That Can Be Validated by the User Based On the Search Criteria

GET /api/v3.0/expense/digitaltaxinvoices

Parameters

Name Type Format Description
offset query string The starting point of the next set of results, after the limit specified in the limit field has been reached.
limit query Int32 The number of records to return. Default value: 25
modifiedafter query string A modification date for the queue record; this parameter can be used to limit the results of the GET request to the queue items that have been added since the last time the validation company queried the queue. The user must have the Web Services Admin role to use this parameter.

Request URL

https://www.concursolutions.com/api/v3.0/expense/digitaltaxinvoices?limit=5

Retrieve a Single Digital Tax Invoice by ID

GET /api/v3.0/expense/digitaltaxinvoices/{id}

Parameters

Name Type Format Description
id path string Required The ID of the digital tax invoice.

Request URL

https://www.concursolutions.com/api/v3.0/expense/digitaltaxinvoices/gWj3IHRYiHZGRTDN6y4r4LN3phszY33HT%24pQ

Update a Specified Digital Tax Invoice

PUT /api/v3.0/expense/digitaltaxinvoices/{id}

Parameters

Name Type Format Description
content body - Required A status update for the digital tax invoice.
id path string Required The ID of the digital tax invoice to update.

Digital Tax Invoices - Schema

Digital Tax Invoices

Name Type Format Description
Items array Digital Tax Invoice The result collection.
NextPage string - The URI of the next page of results, if any.

Digital Tax Invoice

Name Type Format Description
ConcurReceiptID string - Required The ID of the digital tax invoice in plain text.
ID string - The unique identifier of the resource.
URI string - The URI to the resource.
AccountID string - Required The unique identifier assigned by the validation partner to the SAP Concur client company that owns the digital tax invoices.
DocumentID string - Required The ID of the report in plain text.
ReceiptData string - Required The digital tax invoice data.

Request URL

https://www.concursolutions.com/api/v3.0/expense/digitaltaxinvoices/gWj3IHRYiHZGUtIO83ILhbNHqCsjMmkvj%24pQ

Attendees v3

Retrieve all attendees owned by the specified user

Request

URI

Template

GET /api/v3.0/expense/attendees

Parameters

Name Type Format Description
externalID string query The external ID of an attendee. By entering a value for this parameter, you can limit the results to the attendees who match the specified external ID. Up to 10 comma-separated external IDs may be specified.
attendeeTypeID string query The ID of an attendee type. By entering a value for this parameter, you can limit the results to the attendees who match the specified type.
offset string query The starting point of the next set of results, after the limit specified in the limit field has been reached.
limit Int32 query The number of records to return. Default value: 25
user string query The login ID of the user that has added the attendee to an expense. The user who is performing this API request must have the Web Services Admin (Professional) or Can Administer (Standard) user role to use this parameter

Payload

None

Response

Payload

Example

Request

GET https://www.concursolutions.com/api/v3.0/expense/attendees?limit=15

Response

{
  "Items": [
    {
      "AttendeeTypeCode": "NOSHOWS",
      "AttendeeTypeID": "gWjYOjoCmOo2Ua$pH4qnCsQxgS8Z0E",
      "FirstName": null,
      "LastName": "No Show Attendee",
      "MiddleInitial": null,
      "Suffix": null,
      "Company": null,
      "Title": null,
      "ExternalID": null,
      "HasExceptionsPrevYear": false,
      "HasExceptionsYTD": false,
      "TotalAmountPrevYear": 0,
      "TotalAmountYTD": 0,
      "VersionNumber": 1,
      "OwnerName": "System, Concur",
      "OwnerLoginID": "ConcurSystem",
      "CurrencyCode": "USD",
      "Custom1": null,
      "Custom2": null,
      "Custom3": null,
      "Custom4": null,
      "Custom5": null,
      "Custom6": null,
      "Custom7": null,
      "Custom8": null,
      "Custom9": null,
      "Custom10": null,
      "Custom11": null,
      "Custom12": null,
      "Custom13": null,
      "Custom14": null,
      "Custom15": null,
      "Custom16": null,
      "Custom17": null,
      "Custom18": null,
      "Custom19": null,
      "Custom20": null,
      "Custom21": null,
      "Custom22": null,
      "Custom23": null,
      "Custom24": null,
      "Custom25": null,
      "ID": "gWj3IHRYiHZGUtIO83ILhbNHqCsjMmkvj$pQ",
      "URI": "https://www.concursolutions.com/api/v3.0/expense/attendees/gWj3IHRYiHZGUtIO83ILhbNHqCsjMmkvj$pQ"
    }
  ]
}

Retrieve a single attendee by ID

Request

URI

Template

/api/v3.0/expense/attendees/{id}

Parameters

Name Type Format Description
id string path Required The attendee object to create.
user string query The login ID of the user that has added the attendee to an expense. The user who is performing this API request must have the Web Services Admin (Professional) or Can Administer (Standard) user role to use this parameter

Payload

None

Response

Payload

Example

GET https://www.concursolutions.com/api/v3.0/expense/attendees/gWj3IHRYiHZGd0HJy%24p5Uk0zITlsMX0ymT%24pA

Request

Response

{
  "AttendeeTypeCode": "PRIVATE",
  "AttendeeTypeID": "gWjYOjoa7Fe0HsTGEk417OCzqUf1A",
  "FirstName": "Diego",
  "LastName": "Rodriguez",
  "MiddleInitial": null,
  "Suffix": null,
  "Company": "Contoso",
  "Title": null,
  "ExternalID": "1",
  "HasExceptionsPrevYear": false,
  "HasExceptionsYTD": false,
  "TotalAmountPrevYear": 0,
  "TotalAmountYTD": 0,
  "VersionNumber": 1,
  "OwnerName": "System, Concur",
  "OwnerLoginID": "ConcurSystem",
  "CurrencyCode": "USD",
  "Custom1": null,
  "Custom2": null,
  "Custom3": null,
  "Custom4": null,
  "Custom5": null,
  "Custom6": null,
  "Custom7": null,
  "Custom8": null,
  "Custom9": null,
  "Custom10": null,
  "Custom11": null,
  "Custom12": null,
  "Custom13": null,
  "Custom14": null,
  "Custom15": null,
  "Custom16": null,
  "Custom17": null,
  "Custom18": null,
  "Custom19": null,
  "Custom20": null,
  "Custom21": null,
  "Custom22": null,
  "Custom23": null,
  "Custom24": null,
  "Custom25": null,
  "ID": "gWj3IHRYiHZGd0HJy$p5Uk0zITlsMX0ymT$pA",
  "URI": "https://www.concursolutions.com/api/v3.0/expense/attendees/gWj3IHRYiHZGd0HJy$p5Uk0zITlsMX0ymT$pA"
}

Create a new attendee

Request

URI

/api/v3.0/expense/attendees

Template

Parameters

Name Type Format Description
user string query The login ID of the user that has added the attendee to an expense. The user who is performing this API request must have the Web Services Admin (Professional) or Can Administer (Standard) user role to use this parameter

Payload

Response

Payload

Example

POST https://www.concursolutions.com/api/v3.0/expense/attendees

Request

Response

{
  "ID": "gWj3IHRYiHZOQ2T9NNdJ$plN$s7$sG8LhZwjoQ",
  "URI": "https://www.concursolutions.com/api/v3.0/expense/attendees/gWj3IHRYiHZOQ2T9NNdJ$plN$s7$sG8LhZwjoQ"
}

Update existing attendees

Request

URI

Template

/api/v3.0/expense/attendees/{id}

Parameters

Name Type Format Description
id string path Required The attendee ID
user string query The login ID of the user that has added the attendee to an expense. The user who is performing this API request must have the Web Services Admin (Professional) or Can Administer (Standard) user role to use this parameter

Payload

Response

Payload

Example

PUT https://www.concursolutions.com/api/v3.0/expense/attendees/gWj3IHRYiHZOQ2T9NNdJ%24plN%24s7%24sG8LhZwjoQ

Request

Response

ToDo

Attendees v3 - Schema

Attendees

Name Type Format Description
Items array Attendee The result collection.
NextPage string - The URI of the next page of results, if any.

Attendee

Name Type Format Description
AttendeeTypeCode string - A code that indicates the type of attendee. Examples: EMPLOYEE, SPOUSE, BUSGUEST. Maximum length: 40 characters
AttendeeTypeID string - The ID of the attendee type. To obtain the attendee type ID value, use the GET /expense/attendeetypes endpoint. The value of the ID element in the response is the attendee type ID.
Company string - The name of the attendee's company. Maximum length: 150 characters
CurrencyCode string - The 3-letter ISO 4217 currency code for monetary amounts related to an attendee.
Custom1 through Custom25 CustomField - A custom field associated with the attendee. This field may or may not have data, depending on how Expense is configured.
ExternalID string - A unique identifier for the attendee, assigned outside of Concur. Maximum length: 48 characters NOTE: For HCP connectors where information returned to Concur represents one record per attendee+address pair, this value should be a unique identifier for that pair, and the unique identifier for the individual should be placed into a custom field.
FirstName string - The attendee's first name. Maximum length: 50 characters
HasExceptionsPrevYear Boolean - Determines whether the attendee had exceptions in the previous year, based on yearly total limits for attendees. Format: true or false
HasExceptionsYTD Boolean - Determines whether the attendee has exceptions in the current year, based on yearly total limits for attendees. Format: true or false
ID string - The unique identifier of the resource.
LastName string - The attendee's last name. Maximum length: 132 characters
MiddleInitial string - The attendee's middle initial. Maximum length: 1 character
OwnerLoginID string - The login ID of the user who owns the attendee record.
OwnerName string - The name of the user who owns the attendee record.
Suffix string - The attendee's name suffix. Maximum length: 32 characters
Title string - The attendee's title. Maximum length: 32 characters
TotalAmountPrevYear Decimal - The total amount spent on the attendee in the previous calendar year.
TotalAmountYTD Decimal - The total amount spent on the attendee in the current calendar year.
URI string - The URI to the resource.
VersionNumber Int32 - The attendee's version number.

Custom Field

Name Type Format Description
Code string - For list fields, this is the list item code.
ListItemID string - For list fields, this is the list item ID.
Type string - The custom field type. Possible values: Amount, Boolean, ConnectedList, Date, Integer, List, Number, Text
Value string - The value in the Org Unit or Custom field. For list fields, this is the name of the list item. Maximum length: 48 characters

Company Card Transactions

The corporate or credit card charges that are available for use in expense reports for the OAuth consumer.

Retrieves a list of unassigned company card charges for the user specified in the OAuth access token.

Version

1.1

URI

https://www.concursolutions.com/api/expense/expensereport/v1.1/CardCharges

Operations

GET

Company Card Transaction - Request

Request Parameters

None.

Content Types

application/xml

Authorization Header

Authorization header with OAuth token for valid SAP Concur user. Required.

Company Card Transaction - Response

Content Types

application/xml

Company Card Transaction - Schema

This request will return a CardCharges parent element with a CardCharge child element for each transaction.

CardCharge Child Elements

Element Description
CardNumber The number of the card, with all digits obscured OTHER than last 4 digits.
ExpKey The code for the expense type of the transaction
Merchant The merchant name for the transaction.
ExpName The name of the expense type of the transaction.
TransactionAmount The amount of the card transaction.
TransactionCrnCode The currency code of the transaction amount.
TransactionDate The date of the transaction.

Company Card Transaction - Examples

XML Example Request

GET https://www.concursolutions.com/api/expense/expensereport/v1.1/CardCharges/ HTTP/1.1
Authorization: OAuth {access token}
...

XML Example of Successful Response

HTTP/1.1 200 OK
Content-Type: application/xml

<CardCharges
    xmlns="https://www.concursolutions.com/api/expense/expensereport/2011/03">
    <CardCharge>
        <CardNumber>XXXXXXXXX1111</CardNumber>
        <ExpKey>CARRT</ExpKey>
        <ExpName>Car Rental</ExpName>
        <Merchant>Hertz</Merchant>
        <TransactionAmount>283.88000000</TransactionAmount>
        <TransactionCrnCode>USD</TransactionCrnCode>
        <TransactionDate>2010-08-19T00:00:00</TransactionDate>
    </CardCharge>
    <CardCharge>
        <CardNumber>XXXXXXXXX1111</CardNumber>
        <ExpKey>UNDEF</ExpKey>
        <ExpName>Undefined</ExpName>
        <Merchant>King Tires</Merchant>
        <TransactionAmount>274.13000000</TransactionAmount>
        <TransactionCrnCode>USD</TransactionCrnCode>
        <TransactionDate>2010-08-19T00:00:00</TransactionDate>
    </CardCharge>
</CardCharges>

Expense Delegators

Users that have granted delegate permissions to the another Expense user.

Retrieves the list of users that have granted delegate permissions to the user specified in the OAuth access token.

Version

1.1

URI

https://www.concursolutions.com/api/expense/expensereport/v1.1/Delegators

Operations

GET

Expense Delegators - Request

Request Parameters

None.

Headers

Authorization Header

Authorization header with OAuth token for valid SAP Concur user. Required.

Accept Header

application/xml

Expense Delegators- Response

Content Types

application/xml

Expense Delegators - Schema

This request will return a DelegatorsList parent element with a Delegator parent element for each user that has granted delegate rights to the OAuth consumer.

Delegator Elements

Element Description
CanApprove Whether the delegate is granted the right to approve expense reports on behalf of the delegator.
CanPrepare Whether the delegate is granted the right to create expense reports on behalf of the delegator.
CanSubmit Whether the delegate is granted the right to submit expense reports on behalf of the delegator.
CanTemporaryApprove Whether the delegate is granted the same temporary approval rights as the delegator.
CanViewReceipts Whether the delegate is granted the right to view receipts on behalf of the delegator.
ReceiveApprovalEmails Whether the delegate also receives the approval emails sent to the delegator.
ReceivesEmails Whether the delegate also receives the SAP Concur emails sent to the delegator.
DelegatorXUserID The user ID of the delegator.

Expense Delegators - Examples

XML Example Request

GET https://www.concursolutions.com/api/expense/expensereport/v1.1/Delegators HTTP/1.1
Authorization: OAuth {access token}
...

XML Example of Successful Response

HTTP/1.1 200 OK
Content-Type: application/xml

<DelegatorsList xmlns="http://www.concursolutions.com/api/expense/expensereport/2011/03" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
    <Delegator>
        <CanApprove>N</CanApprove>
        <CanPrepare>Y</CanPrepare>
        <CanSubmit>Y</CanSubmit>
        <CanTemporaryApprove>N</CanTemporaryApprove>
        <CanViewReceipts>Y</CanViewReceipts>
        <ReceiveApprovalEmails>N</ReceiveApprovalEmails>
        <ReceivesEmails>N</ReceivesEmails>
        <DelegatorXUserID>terryb@example.com</DelegatorXUserID>
    </Delegator>
    <Delegator>
        <CanApprove>N</CanApprove>
        <CanPrepare>Y</CanPrepare>
        <CanSubmit>Y</CanSubmit>
        <CanTemporaryApprove>N</CanTemporaryApprove>
        <CanViewReceipts>N</CanViewReceipts>
        <ReceiveApprovalEmails>N</ReceiveApprovalEmails>
        <ReceivesEmails>N</ReceivesEmails>
        <DelegatorXUserID>patd@example.com</DelegatorXUserID>
    </Delegator>
</DelegatorsList>

Expense Entry Attendee v3

Prior Versions

2.0 documentation is available here.

Retrieve All Entry-Attendee Associations Owned by the User

GET /api/v3.0/expense/entryattendeeassociations

Parameters

Name Type Format Description
entryID string query The ID of the entry for which to retrieve entry-attendee associations.
offset string query The starting point of the next set of results, after the limit specified in the limit field has been reached.
limit Int32 query The number of records to return. Default value: 25
user string query The login ID of the user who owns this entry-attendee association. The user must have the Web Services Admin role to use this parameter.

Request URL

https://www.concursolutions.com/api/v3.0/expense/entryattendeeassociations?limit=15&user=ALL

JSON Example of a Successful Response

{
  "Items": [
    {
      "EntryID": "gWidFO7ikXS264Tf3Z68NmcXdkxhcxezfzA",
      "AttendeeID": "gWj3IHRYiHZGX4xP$s0YUWUyoUjss$pWV3z$pQ",
      "Amount": 80,
      "AssociatedAttendeeCount": 1,
      "Custom1": null,
      "Custom2": null,
      "Custom3": null,
      "Custom4": null,
      "Custom5": null,
      "ID": "gWgSNsCedFvv8LE1LrkughW9mAyCN",
      "URI": "https://www.concursolutions.com/api/v3.0/expense/entryattendeeassociations/gWgSNsCedFvv8LE1LrkughW9mAyCN"
    },
    {
      "EntryID": "gWidFO7ikXSi7DX4hlLTggJD76w1IvtEvWw",
      "AttendeeID": "gWj3IHRYiHZGSG6M4xo0PEyYXAs8rHGfD$pQ",
      "Amount": 120,
      "AssociatedAttendeeCount": 1,
      "Custom1": null,
      "Custom2": null,
      "Custom3": null,
      "Custom4": null,
      "Custom5": null,
      "ID": "gWgOOsCJrozFymvWtfB5Ri1WD$ste9",
      "URI": "https://www.concursolutions.com/api/v3.0/expense/entryattendeeassociations/gWgOOsCJrozFymvWtfB5Ri1WD$ste9"
    }
  ]
}

Retrieve an Entry-Attendee Association by ID

GET /api/v3.0/expense/entryattendeeassociations/{id}

Parameters

Name Type Format Description
id string path Required The ID of the entry-attendee association.
user string query The login ID of the user who owns this entry-attendee association. The user must have the Web Services Admin role to use this parameter.

Request URL

https://www.concursolutions.com/api/v3.0/expense/entryattendeeassociations/gWgSM%24s2kvfcQ8xC%24p6uaPsY6V6qB7FqOU

JSON Example of a Successful Response

{
  "EntryID": "gWidFO7ikXV67u6QrT2w1Yhqzh4a8j$pEjCg",
  "AttendeeID": "gWj3IHRYiHZOTjq8PONWIqyRFfGz4RoozoQ",
  "Amount": 17.01,
  "AssociatedAttendeeCount": 1,
  "Custom1": null,
  "Custom2": null,
  "Custom3": null,
  "Custom4": null,
  "Custom5": null,
  "ID": "gWgSM$s2kvfcQ8xC$p6uaPsY6V6qB7FqOU",
  "URI": "https://www.concursolutions.com/api/v3.0/expense/entryattendeeassociations/gWgSM$s2kvfcQ8xC$p6uaPsY6V6qB7FqOU"
}

Create a New Entry-Attendee Association

POST /api/v3.0/expense/entryattendeeassociations

Parameters

Name Type Format Description
content - body Required The EntryAttendeeAssociation object to create.

Request URL

https://www.concursolutions.com/api/v3.0/expense/entryattendeeassociations

JSON Example of a Successful Response

{
  "ID": "gWgSM$s2kvfcQ8xC$p6uaPsY6V6qB7FqOU",
  "URI": "https://www.concursolutions.com/api/v3.0/expense/entryattendeeassociations/gWgSM$s2kvfcQ8xC$p6uaPsY6V6qB7FqOU"
}

Update a Specified Entry-Attendee Association

PUT /api/v3.0/expense/entryattendeeassociations/{id}

Parameters

Name Type Format Description
id string path Required The ID of the entry-attendee association.
content - body Required The partial or complete EntryAttendeeAssociation object to update.

Delete a Specified Entry-Attendee Association

DELETE /api/v3.0/expense/entryattendeeassociations/{id}

Request URL

https://www.concursolutions.com/api/v3.0/expense/entryattendeeassociations/gWgSM%24s2kvfcQ8xC%24p6uaPsY6V6qB7FqOU

JSON Example of a Successful Response

no content

Parameters

Name Type Format Description
id string path Required The connection request ID.

Expense Entry Attendee - Schema

Entry Attendee Associations

Name Type Format Description
Items array Entry Attendee Association The result collection.
NextPage string - The URI of the next page of results, if any.

Entry Attendee Association

Name Type Format Description
Amount Decimal - The portion of the entry transaction amount assigned to this attendee.
AssociatedAttendeeCount Int32 - The count of additional attendees associated with this attendee. A count greater than 1 means there are unnamed attendees associated with this attendee.
AttendeeID string - The unique identifier of the associated attendee. To obtain the attendee ID value, use the GET /expense/attendees endpoint. The value of the ID element in the response is the attendee ID.
Custom1 through Custom5 string - The details from the Custom fields. These fields may not have data, depending on the configuration.
EntryID string - The unique identifier of the associated entry. To obtain the attendee ID value, use the GET /expense/entries endpoint. The value of the ID element in the response is the entry ID.
ID string - The unique identifier of the resource.
URI string - The URI to the resource.

Entries

The SAP Concur Expense Entries API is used to manage expense reports and their entries in SAP Concur. It allows for the synchronizing and reconciliation of expense related information with your internal systems and reporting modules.

1.1 documentation is available here.

Retrieve All Expense Entries

Version 2.0, covers a wider range of partner scenarios and is recommended as the first step. However, depending on the entries you need to retrieve, using a combination of version 2.0 and version 3.0 should be considered. To see examples, review the VAT Reclaim integration guide.

Create a New Expense Entry

POST /api/v3.0/expense/entries

Parameters

Name Type Format Description
content body - Required The expense entry object to create.
user string query The login ID of the user who owns the entries.

Request URL

https://www.concursolutions.com/api/v3.0/expense/entries

JSON Example of a Successful Response

{
  "ID": "gWidFO7ikXV647DRpQmvCXeFNA4VPTOczCg",
  "URI": "https://www.concursolutions.com/api/v3.0/expense/entries/gWidFO7ikXV647DRpQmvCXeFNA4VPTOczCg"
}

Updates an Expense Entry

PUT /api/v3.0/expense/entries/{id}

Parameters

Name Type Format Description
id string path Required The expense entry ID.
content body - Required The partial or complete expense entry object to update.

Request URL

https://www.concursolutions.com/api/v3.0/expense/entries/gWidFO7ikXV66iSvqtG6Yd0wZ%24s4ftzvzTCg

Delete an Expense Entry

DELETE /api/v3.0/expense/entries/{id}

Parameters

Name Type Format Description
id string path Required The ID of the expense entry to delete.
user string query The login ID of the user who owns the entries.

Request URL

https://www.concursolutions.com/api/v3.0/expense/entries/gWidFO7ikXV66iSvqtG6Yd0wZ%24s4ftzvzTCg

Schema

Entries

Name Type Format Description
Items array Entry The result collection.
NextPage string - The URI of the next page of results, if any.

Entry

Name Type Format Description
AllocationType string - The type of allocations for the expense. Supported values: P - partial allocation, F - full allocation, N - no allocation. Use the GET /expense/allocations function to get information about this entry's allocations.
ApprovedAmount decimal - The approved amount of the expense entry, in the report currency.
CompanyCardTransactionID string - The unique identifier for a company card transaction that is associated with this expense. Concur Expense uses the Credit Card Import job to import company card transactions. Use the GET CompanyCardTransactions function to get information about these card transactions. This element is null when there is no company card transaction associated with this expense.
Custom1 through Custom40 customField - The details from the Custom fields. These fields may not have data, depending on the configuration.
Comment string - A comment that describes the expense entry. Maximum length: 500 characters
Description string - The description of the expense. Maximum length: 64 characters
ElectronicReceiptID string - The unique identifier for an eReceipt that is associated with this expense. Use the GET eReceipts function to get information about this eReceipt. This element is null when there is no eReceipt associated with this expense.
EmployeeBankAccountID string - The unique identifier of an employee bank account that is associated with this expense. Typically, this element is used when Expense Pay reimburses the employee for this expense. Use the GET BankAccounts function to get information about this bank account.
ExchangeRate decimal - The currency conversion rate that converts the transaction amount that is in the transaction currency into the posted amount that is in the report currency. This element is typically not provided. If this element is empty for transactions in a currency different than the user's reimbursement currency, Expense will use the company's configured exchange rates to determine the posted amount for the transaction. If the system is not able to determine the exchange rate, a value of 1.0 will be used.
ExpenseTypeCode string - Required The code for the expense type. Use GET /expense/expensegroupconfigurations to learn the expense type code for expense types that are active for this report's policy.
ExpenseTypeName string - The name of the expense type, localized to the user's language.
FormID string - The ID of the form used by this expense entry.
HasAppliedCashAdvance boolean true / false Whether the entry has a cash advance applied to it.
HasAttendees boolean true / false Indicates whether the expense has attendees. Use the GET /expense/entryattendeeassociations function to get information about this entry's attendees.
HasComments boolean true / false Whether or not the expense entry has comments.
HasExceptions boolean true / false Whether the expense has exceptions. Use the GET ExpenseEntryExceptions function to get information about this entry's exceptions.
HasImage boolean true / false Indicates whether there is an entry image attached to the entry. Use the GET Entry Images function to get this entry image.
HasItemizations boolean true / false Indicates whether the expense has itemizations. Use the GET /expense/itemizations function to get information about this entry's itemizations.
HasVAT boolean true / false Indicates whether the entry has VAT data.
ID string - The unique identifier of the resource.
IsBillable boolean true / false Indicates whether the expense is billable.
IsImageRequired boolean true / false Indicates whether an entry image is required for the entry.
IsPaidByExpensePay boolean true / false Whether the entry is paid using the Expense Pay service. This element has a value if the report has reached the Processing Payment workflow step, because this is when Concur Expense determines whether it will be paid by Expense Pay.
IsPersonal boolean true / false Indicates whether the expense is personal (that is, non-reimbursable).
IsPersonalCardCharge boolean true / false Indicates whether the expense entry was imported from a personal card feed. Concur Expense uses the Yodlee API to import these card transactions.
Journey journey - Journey data. This element is used when the entry is a mileage expense. For expense types with an expense code that is either Company Car or Personal Car, the Journey child element is required. This element should not be used for expense types with an expense code that is neither Company Car nor Personal Car.
LastModified dateTime - The UTC date when the entry was last modified.
LocationCountry string - The 2-letter ISO 3166-1 country code where the expense was incurred.
LocationID string - The unique identifier for the location where the expense was incurred. Use the GET /common/locations function to get information for this location.
LocationName string - The location where the expense was incurred, usually the city name.
LocationSubdivision string - The ISO 3166-2:2007 country subdivision state, province, or other country subdivision where the expense was incurred.
OrgUnit1 through OrgUnit6 customField - The details from the Org Unit fields. These fields may not have data, depending on the configuration.
PaymentTypeID string - Required The ID of the payment type for the entry. Use GET /expense/expensegroupconfigurations to learn the payment type ID for payment types that are active for this report's expense group. For mileage expenses, use the Cash payment type. For expense types with an expense code that uses a transaction amount instead of a distance, this element is required. This element should not be used for expense types with an expense code for Company Car or Personal Car, because these two expense codes always use the Cash payment type.
PaymentTypeName string - The name of the payment type, localized to the user's language.
PostedAmount decimal - The amount of the expense entry, in the report currency.
ReceiptReceived boolean true / false Indicates whether this entry has been reviewed by a processor. Format: true or false
ReportID string - Required The report ID of the report where the entry will be added.
ReportOwnerID string - The login ID of the report owner. Use the GET User Information function to learn details about this user.
SpendCategoryCode string - The ID of the spending category that is specified for this expense entry.
SpendCategoryName string - The name of the spending category that is specified for this expense entry, localized to the user's language.
TaxReceiptType string - The receipt type for this entry. Supported values: T - tax receipt, R - regular receipt, N - no receipt
TransactionAmount decimal - Required The amount of the expense entry, in the transaction currency paid to the vendor.
TransactionCurrencyCode string - Required The 3-letter ISO 4217 currency code for the expense entry transaction amount. This is the currency in which the vendor was paid. For expense types with an expense code that uses a transaction amount instead of a distance, this element is required. This element should not be used for expense types with an expense code for Company Car or Personal Car, because for these two expense codes the currency is always the Report Currency.
TransactionDate dateTime YYYY-MM-DD Required The date when the good or service associated with this expense entry was provided.
TripID string - The unique identifier of a trip in the Itinerary Service that includes a travel booking associated with this expense. Use GET ItineraryDetails to get information about this trip and the travel booking. This element is null when there is no trip associated with the expense.
URI string - The URI to the resource.
VendorDescription string - The name of the vendor for the expense entry. Maximum length: 64 characters
VendorListItemID string - The unique identifier for a vendor list item. Use the GET /common/lists function to get information about this list item.
VendorListItemName string - The name of an item from a vendor list.

CustomField

Name Type Format Description
Code string - For list fields, this is the list item code.
ListItemID string - For list fields, this is the list item ID.
Type string - The custom field type. Supported values: Amount, Boolean, ConnectedList, Date, Integer, List, Number, Text
Value string - The value in the Org Unit or Custom field. For list fields, this is the name of the list item. Maximum length: 48 characters

Journey

Name Type Format Description
BusinessDistance Int32 - The portion of the journey for business use, in the report owner's unit of measure for distances. This element is required in order to post a personal car mileage expense entry, or to post a company car mileage expense when there is no PersonalDistance value. When using the Odometer elements, the sum of PersonalDistance and BusinessDistance must equal the difference between OdometerEnd and OdometerStart.
EndLocation string - Required Indicates where the journey ended. This is also known as the "To Location". Maximum length: 100 characters
NumberOfPassengers Int32 - The number of people in the vehicle during the journey. Used with Variable-Rate, Personal or Company Car.
OdometerEnd Int32 - The odometer reading at the end of the journey. The value must be greater than the OdometerStart value. This element is used with Variable-Rate and Company Car configuration types.
OdometerStart Int32 - The odometer reading at the start of the journey. This element is used with Variable-Rate and Company Car configuration types.
PersonalDistance Int32 - The portion of the journey for personal use. This element is required in order to post a company car mileage expense when there is no BusinessDistance value. When using the Odometer elements, the sum of PersonalDistance and BusinessDistance must equal the difference between OdometerEnd and OdometerStart. Used with Company Car configuration types.
StartLocation string - Required Indicates where the journey started. This is also known as the "From Location". Maximum length: 100 characters
UnitOfMeasure string - Required The unit of measure for distance and odometer values. Supported values: M - miles, K - kilometers

NOTE: Clients that have Car Configurations that include variable rates or custom mileage expense type codes are not supported. We only support Car Configurations that include Personal Car One-Rate definitions, using the default mileage expense type code (MILEG) where Google Maps is not set as mandatory.

Expense Form Field

The configured fields for the specified expense form.

Version

1.1

URI

https://www.concursolutions.com/api/expense/expensereport/v1.1/report/Form/_{FormId}_/Fields

Operations

GET

Get a List of Form Fields

Retrieves the details of the configured form fields for the specified form.

NOTE: When sending in requests using these fields, be sure to include the required fields from the form and any additional required fields specified in the request documentation.

Expense Form Field - Request

Request Parameters

Parameter Required/Optional Description
{FormId}/Fields required The unique identifier for the desired form and the Fields keyword.

Example: https://www.concursolutions.com/api/expense/expensereport/v1.1/report/Form/{FormId}/Fields

URI Source: The FormId is returned in the FormId element by the Get Form Data function.

Headers

Authorization Header

Authorization header with OAuth token for valid SAP Concur user. Required.

Accept Header

application/xml

Expense Form Field - Response

Expense Form Field - Response Schema

This request will return a FormFieldsList parent element with a FormField parent element for each configured form field.

FormField Elements

Element Description
Id The form field ID.
Label The form field label.
ControlType The type of field.
DataType The type of data accepted by the field.
MaxLength The maximum length of the field value.
Required Whether the field is required.
Cols The number of columns the field contains.
Access The access level the specified user has to the field.
Width The width of the field.
Custom Whether the field is custom.
Sequence The field order on the form.

XML Example Request

GET https://www.concursolutions.com/api/expense/expensereport/v1.1/report/Form/nAaT8$puKKO2$pEVlsXfSruLpDfZL0wVM$s7/Fields HTTP/1.1
Authorization: OAuth {access token}
...

XML Example of Successful Response

HTTP/1.1 200 OK
Content-Type: application/xml

<FormFieldsList xmlns="https://www.concursolutions.com/api/expense/expensereport/2011/03" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
    <FormField>
        <Id>Name</Id>
        <Label>ReportName</Label>
        <ControlType>edit</ControlType>
        <DataType>VARCHAR</DataType>
        <MaxLength>32</MaxLength>
        <Required>Y</Required>
        <Cols>32</Cols>
        <Access>RW</Access>
        <Width>32</Width>
        <Custom>N</Custom>
        <Sequence>1</Sequence>
    </FormField>
    <FormField>
        <Id>ReportId</Id>
        <Label>ReportID</Label>
        <ControlType>static</ControlType>
        <DataType>VARCHAR</DataType>
        <MaxLength>32</MaxLength>
        <Required>Y</Required>
        <Cols />
        <Access>RO</Access>
        <Width />
        <Custom>N</Custom>
        <Sequence>2</Sequence>
    </FormField>
    <FormField>
        <Id>PolKey</Id>
        <Label>Policy</Label>
        <ControlType>picklist</ControlType>
        <DataType>INTEGER</DataType>
        <MaxLength />
        <Required>Y</Required>
        <Cols />
        <Access>RW</Access>
        <Width />
        <Custom>N</Custom>
        <Sequence>3</Sequence>
    </FormField>
    <FormField>
        <Id>EmpName</Id>
        <Label>EmployeeName</Label>
        <ControlType>static</ControlType>
        <DataType>VARCHAR</DataType>
        <MaxLength>32</MaxLength>
        <Required>Y</Required>
        <Cols />
        <Access>HD</Access>
        <Width />
        <Custom>N</Custom>
        <Sequence>4</Sequence>
    </FormField>
    <FormField>
        <Id>UserDefinedDate</Id>
        <Label>ReportDate</Label>
        <ControlType>edit</ControlType>
        <DataType>TIMESTAMP</DataType>
        <MaxLength />
        <Required>N</Required>
        <Cols />
        <Access>RW</Access>
        <Width />
        <Custom>N</Custom>
        <Sequence>5</Sequence>
    </FormField>
    <FormField>
        <Id>Purpose</Id>
        <Label>BusinessPurpose</Label>
        <ControlType>textarea</ControlType>
        <DataType>VARCHAR</DataType>
        <MaxLength>500</MaxLength>
        <Required>Y</Required>
        <Cols>32</Cols>
        <Access>RW</Access>
        <Width>32</Width>
        <Custom>N</Custom>
        <Sequence>6</Sequence>
    </FormField>
</FormFieldsList>

Expense Form

The configured expense forms in SAP Concur. Clients can have multiple forms configured for each form type.

Version

1.1

URI

https://www.concursolutions.com/api/expense/expensereport/v1.1/report/Forms/

Operations

GET

Get Form Types

Retrieves the list of configured form types.

Request

Request Parameters

None.

Headers

Authorization Header

Authorization header with OAuth token for valid SAP Concur user. Required.

Accept Header

application/xml

Response

Get Form Types Schema

This request will return a FormTypesList parent element with a FormType parent element for each configured form.

FormType Elements

Element Description
Name The form type name.
FormCode The form type code.

Examples

XML Example Request

GET https://www.concursolutions.com/api/expense/expensereport/v1.1/report/Forms HTTP/1.1
Authorization: OAuth {access token}
...

XML Example of Successful Response

HTTP/1.1 200 OK
Content-Type: application/xml

<FormTypesList
    xmlns="http://www.concursolutions.com/api/expense/expensereport/2011/03"
    xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
    <FormType>
        <Name>Expense Entry</Name>
        <FormCode>ENTRYINFO</FormCode>
    </FormType>
    <FormType>
        <Name>Expense Report Header</Name>
        <FormCode>RPTINFO</FormCode>
    </FormType>
    <FormType>
        <Name>Expense Allocation</Name>
        <FormCode>ALLOCINFO</FormCode>
    </FormType>
    <FormType>
        <Name>Expense Attendee</Name>
        <FormCode>ATTNINFO</FormCode>
    </FormType>
    <FormType>
        <Name>Authorization Request Expense Category</Name>
        <FormCode>TRAVELREQENTRYINFO</FormCode>
    </FormType>
    <FormType>
        <Name>Authorization Request Header</Name>
        <FormCode>TRAVELREQINFO</FormCode>
    </FormType>
    <FormType>
        <Name>Expense Detail View</Name>
        <FormCode>EXPLISTDTL</FormCode>
    </FormType>
    <FormType>
        <Name>Attendee Detail View</Name>
        <FormCode>ATNLISTDTL</FormCode>
    </FormType>
    <FormType>
        <Name>Expense Car</Name>
        <FormCode>CARINFO</FormCode>
    </FormType>
</FormTypesList>

Get Form Data

Retrieves the list of configured forms for the specified form type.

Request

Request Parameters

Parameter Required/Optional Description
FormCode required The identifier for the desired form.

Example: https://www.concursolutions.com/api/expense/expensereport/v1.1/report/Forms/{FormCode}

URI Source: The FormCode is returned in the FormCode element in the Get Form Types response.

Headers

Authorization Header

Authorization header with OAuth token for valid SAP Concur user.

Accept Header

application/xml

Response

Get Form Data Schema

This request will return a FormDataList parent element with a FormData parent element for each configured form.

FormData Elements

Element Description
Name The form name.
FormId The form identifier.

Examples

XML Example Request

GET https://www.concursolutions.com/api/expense/expensereport/v1.1/report/Forms/RPTINFO HTTP/1.1
Authorization: OAuth {access token}
...

XML Example of Successful Response

HTTP/1.1 200 OK
Content-Type: application/xml

<FormDataList xmlns="http://www.concursolutions.com/api/expense/expensereport/2011/03" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
    <FormData>
        <Name>Central Reconciliation Columns</Name>
        <FormId>nAaT8$puKKOG5E4R9gCMyXVrFjo9NIbmQl</FormId>
    </FormData>
    <FormData>
        <Name>Central Reconciliation Report</Name>
        <FormId>nAaT8$puKKOGmK3xvAdnAOgJ9fxaoXjyW$s</FormId>
    </FormData>
    <FormData>
        <Name>Default Report Information</Name>
        <FormId>nAaT8$puKKO2$pEVlsXfSruLpDfZL0wVM$s7</FormId>
    </FormData>
</FormDataList>

Expense Group Configurations

Retrieves the list of Expense Polices, Expense Types and Payment Types for the Expense Group the user specified in the OAuth access token is assigned to. Each Expense Policy contains a list of valid Expense Types. The Payment Types are associated with the user’s Expense Group and apply to all the returned policies. Only the payment types that are valid for the Post Expense Entry endpoint are returned.

NOTE: The Concur Expense product is highly configurable, and each client may have a unique set of payment types. If a payment type is not included in the response, it is not available for use with this client.

Version

3.0

1.1 documentation is available here

Retrieve a configuration of an expense group

GET /api/v3.0/expense/expensegroupconfigurations

Parameters

Name Type Format Description
user string query The login ID of the user associated with this expense group configuration. The user must have the Web Services Admin role to use this parameter.
offset string query The starting point of the next set of results, after the limit specified in the limit field has been reached.
limit Int32 query The number of records to return Default value: 10

Request URL

https://www.concursolutions.com/api/v3.0/expense/expensegroupconfigurations?user=ALL&limit=10

JSON example of a successful response

{
  "Items": [
    {
      "Name": "United Kingdom",
      "AttendeeListFormID": "gWh2aF2cfwJElRBMIJ9ahYnTVXDIp1fQUdg",
      "AttendeeListFormName": "Default Attendee Detail View",
      "AllowUserRegisterYodlee": false,
      "AllowUserDigitalTaxInvoice": false,
      "CashAdvance": null,
      "PaymentTypes": [
        {
          "ID": "gWurF7TC$pQAT4cqT0JokiYMobzQdz",
          "Name": "Cash",
          "IsDefault": false
        },
        {
          "ID": "gWurL7jy84a4BAdqGaTNrtiABiqpM",
          "Name": "Company Paid",
          "IsDefault": false
        },
        {
          "ID": "gWvnH$pTyEPYFerdCk8rjvoSpmM4L0",
          "Name": "Pending Card Transaction",
          "IsDefault": false
        }
      ],
      "Policies": [
        {
          "ID": "gWmINGEAkRfLbo7HmBh5USB3$pS8HMWDoP2Q",
          "Name": "*Global Expense Policy",
          "IsDefault": false,
          "IsInheritable": true,
          "ExpenseTypes": [
            {
              "Code": "LODNG",
              "Name": "Hotel",
              "ExpenseCode": "LODGING"
            }
          ]
        }
      ]
    }
  ]
}

Retrieve an expense group configuration by ID

GET /api/v3.0/expense/expensegroupconfigurations/{id}

Parameters

Name Type Format Description
id string path Required The ID of the expense group configuration.
user string query The login ID of the user associated with this expense group configuration. The user must have the Web Services Admin role to use this parameter.

Expense Group Configurations - Schema

Expense Group Configurations

Name Type Format Description
id string path Required The ID of the expense group configuration.
user string query The login ID of the user associated with this expense group configuration. The user must have the Web Services Admin role to use this parameter.

Expense Group Configuration

Name Type Format Description
AllowUserDigitalTaxInvoice Boolean - Indicates whether users are allowed to upload digital tax invoices. Format: true or false
AllowUserRegisterYodlee Boolean - Indicates whether users in the expense group are allowed to register Yodlee credit cards. Format: true or false
AttendeeListFormID string - The unique identifier for the attendee list form.
AttendeeListFormName string - The name of the attendee list form.
AttendeeTypes array[AttendeeType] - The list of attendee types.
CashAdvance CashAdvance - The amount of the cash advance.
ID string - The unique identifier of the resource.
Name string - The name of the expense group configuration.
PaymentTypes array Payment Type The list of payment types.
Policies array Policy The list of policies and expense types.
URI string - The URI to the resource.

Attendee Type

Name Type Format Description
Code string - The attendee type code.
Name string - The name of the attendee type.

Cash Advance

Name Type Format Description
AllowUserCarryBalance Boolean - Indicates whether users are allowed to carry a cash advance balance forward from one report to another. Format: true or false
AllowUserLinkMultiple Boolean - Indicates whether users are allowed to link multiple cash advances to one expense report. Format: true or false
AllowUserUpdateExchangeRate Boolean - Indicates whether users are allowed to update the currency exchange rate for expense entries. Format: true or false
Name string - The name of the cash advance workflow.
WorkflowID string - The unique identifier for the cash advance workflow. Null means there is no such workflow.

Payment Type

Name Type Format Description
ID string - The unique identifier of the resource.
IsDefault Boolean - Determines whether this payment type is the default. Format: true or false
Name string - The name of the payment type.

Policy

Name Type Format Description
ExpenseTypes array ExpenseType The parent element for the list of expense types in the policy.
ID string - The unique identifier of the resource.
IsDefault Boolean - Indicates whether this policy is the default. Format: true or false
IsInheritable Boolean - Indicates whether the descendent nodes in the Expense Feature Hierarchy are covered by this policy. Format: true or false
Name string - The name of the policy.

Expense Group Configurations - Expense Type

Name Type Format Description
Code string - The code for the expense type. Expense types define expenses within an expense category. For example, Business Meal is an expense type in the MEALS category.
ExpenseCode string - The code for the expense category. The expense category code controls the function of an expense entry. Format: OTHER - Standard, COCARMILE - Company Car, PCARMILE - Personal Car, MFUEL - Fuel For Mileage, LODGING - Lodging, MEALS - Meals, OTHERNP - Other Not Partially Approvable, JPYPTRAN - Japanese Public Transportation
Name string - The name of the expense type.

Request URL

https://www.concursolutions.com/api/v3.0/expense/expensegroupconfigurations/gWv5bj%24sPY1weV9audTTRp7PkBlea3Y6aizg

JSON example of a successful response

{
  "Name": "United Kingdom",
  "AttendeeListFormID": "gWh2aF2cfwJElRBMIJ9ahYnTVXDIp1fQUdg",
  "AttendeeListFormName": "Default Attendee Detail View",
  "AllowUserRegisterYodlee": false,
  "AllowUserDigitalTaxInvoice": false,
  "CashAdvance": null,
  "PaymentTypes": [
    {
      "ID": "gWurF7TC$pQAT4cqT0JokiYMobzQdz",
      "Name": "Cash",
      "IsDefault": false
    },
    {
      "ID": "gWurL7jy84a4BAdqGaTNrtiABiqpM",
      "Name": "Company Paid",
      "IsDefault": false
    },
    {
      "ID": "gWvnH$pTyEPYFerdCk8rjvoSpmM4L0",
      "Name": "Pending Card Transaction",
      "IsDefault": false
    }
  ],
  "Policies": [
    {
      "ID": "gWmINGEAkRfLbo7HmBh5USB3$pS8HMWDoP2Q",
      "Name": "*Global Expense Policy",
      "IsDefault": false,
      "IsInheritable": true,
      "ExpenseTypes": [
        {
          "Code": "LODNG",
          "Name": "Hotel",
          "ExpenseCode": "LODGING"
        },
        {
          "Code": "LODTX",
          "Name": "Hotel Tax",
          "ExpenseCode": "LODGING"
        },
        {
          "Code": "LNDRY",
          "Name": "Laundry",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "AIRFR",
          "Name": "Airfare",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "01026",
          "Name": "Airline Fees",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "CARRT",
          "Name": "Car Rental",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "CARMI",
          "Name": "Company Car Mileage",
          "ExpenseCode": "COCARMILE"
        },
        {
          "Code": "GASXX",
          "Name": "Fuel",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "PARKG",
          "Name": "Parking",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "MILEG",
          "Name": "Personal Car Mileage",
          "ExpenseCode": "PCARMILE"
        },
        {
          "Code": "TRAIN",
          "Name": "Public Transport",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "TAXIX",
          "Name": "Taxi",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "TOLLS",
          "Name": "Tolls/Road Charges",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "01025",
          "Name": "Train",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "BRKFT",
          "Name": "Breakfast",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "DINNR",
          "Name": "Dinner",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "01028",
          "Name": "Individual Meals",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "LUNCH",
          "Name": "Lunch",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "BUSML",
          "Name": "Entertainment - Clients",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "01004",
          "Name": "Entertainment - Staff",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "01005",
          "Name": "Courier/Shipping/Freight",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "OFCSP",
          "Name": "Office Equipment/Hardware",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "01007",
          "Name": "Office Supplies/Software",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "POSTG",
          "Name": "Postage",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "01006",
          "Name": "Printing/Photocopying/Stationery",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "01035",
          "Name": "Business Calls",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "ONLIN",
          "Name": "Internet/Online Fees",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "CELPH",
          "Name": "Mobile/Cellular Phone",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "01036",
          "Name": "Non-Business Calls",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "LOCPH",
          "Name": "Telephone/Fax",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "BANKF",
          "Name": "Bank Fees",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "01024",
          "Name": "Currency Exchange Fees",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "01011",
          "Name": "Medical Fees",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "01008",
          "Name": "Passports/Visa Fees",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "AWRDS",
          "Name": "Gifts - Clients",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "GIFTS",
          "Name": "Gifts - Staff",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "TRDSH",
          "Name": "Marketing/Promotional Costs",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "MISCL",
          "Name": "Miscellaneous",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "01014",
          "Name": "Newspapers/Magazines/Books",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "DUESX",
          "Name": "Professional Subscriptions/Dues",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "SEMNR",
          "Name": "Seminar/Course fees",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "01009",
          "Name": "Tips/Gratuities",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "01012",
          "Name": "Tuition/Training Reimbursement",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "01010",
          "Name": "Ex Pat Expenses",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "01017",
          "Name": "Relocation Expenses",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "CSHRN",
          "Name": "Cash Advance Return",
          "ExpenseCode": "OTHERNP"
        },
        {
          "Code": "CURGL",
          "Name": "Currency Gain/Loss",
          "ExpenseCode": "OTHERNP"
        },
        {
          "Code": "01052",
          "Name": "Fixed Vehicle Reimbursement",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "01053",
          "Name": "Motus Other Amount",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "01054",
          "Name": "Variable Vehicle Reimbursement",
          "ExpenseCode": "OTHER"
        }
      ]
    },
    {
      "ID": "gWmINGEAkRfGsCKjw8DAec1dbfF$pV$sxbfpw",
      "Name": "Germany Expense Policy",
      "IsDefault": null,
      "IsInheritable": null,
      "ExpenseTypes": [
        {
          "Code": "LODNG",
          "Name": "Hotel",
          "ExpenseCode": "LODGING"
        },
        {
          "Code": "LODTX",
          "Name": "Hotel Tax",
          "ExpenseCode": "LODGING"
        },
        {
          "Code": "LNDRY",
          "Name": "Laundry",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "AIRFR",
          "Name": "Airfare",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "01026",
          "Name": "Airline Fees",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "01002",
          "Name": "Car Maintenance/Repairs ",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "CARRT",
          "Name": "Car Rental",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "GASXX",
          "Name": "Fuel",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "PARKG",
          "Name": "Parking",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "MILEG",
          "Name": "Personal Car Mileage",
          "ExpenseCode": "PCARMILE"
        },
        {
          "Code": "TRAIN",
          "Name": "Public Transport",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "TAXIX",
          "Name": "Taxi",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "TOLLS",
          "Name": "Tolls/Road Charges",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "01025",
          "Name": "Train",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "BRKFT",
          "Name": "Breakfast",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "DINNR",
          "Name": "Dinner",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "LUNCH",
          "Name": "Lunch",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "01055",
          "Name": "EBR 1190",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "01030",
          "Name": "Entertainment - External (Domestic)",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "01031",
          "Name": "Entertainment - External (Foreign)",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "01004",
          "Name": "Entertainment - Staff",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "01005",
          "Name": "Courier/Shipping/Freight",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "OFCSP",
          "Name": "Office Equipment/Hardware",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "01007",
          "Name": "Office Supplies/Software",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "POSTG",
          "Name": "Postage",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "01006",
          "Name": "Printing/Photocopying/Stationery",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "01035",
          "Name": "Business Calls",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "ONLIN",
          "Name": "Internet/Online Fees",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "CELPH",
          "Name": "Mobile/Cellular Phone",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "01036",
          "Name": "Non-Business Calls",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "LOCPH",
          "Name": "Telephone/Fax",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "BANKF",
          "Name": "Bank Fees",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "01024",
          "Name": "Currency Exchange Fees",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "01011",
          "Name": "Medical Fees",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "01008",
          "Name": "Passports/Visa Fees",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "01033",
          "Name": "Gifts <= 35€",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "01032",
          "Name": "Gifts > 35€",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "TRDSH",
          "Name": "Marketing/Promotional Costs",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "MISCL",
          "Name": "Miscellaneous",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "01014",
          "Name": "Newspapers/Magazines/Books",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "DUESX",
          "Name": "Professional Subscriptions/Dues",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "SEMNR",
          "Name": "Seminar/Course fees",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "01009",
          "Name": "Tips/Gratuities",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "01012",
          "Name": "Tuition/Training Reimbursement",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "01010",
          "Name": "Ex Pat Expenses",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "01017",
          "Name": "Relocation Expenses",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "CSHRN",
          "Name": "Cash Advance Return",
          "ExpenseCode": "OTHERNP"
        },
        {
          "Code": "CURGL",
          "Name": "Currency Gain/Loss",
          "ExpenseCode": "OTHERNP"
        }
      ]
    },
    {
      "ID": "gWmINGEAkQoarrf1JiyI8$sqI$s00T30OfIlA",
      "Name": "Italy Expense Policy",
      "IsDefault": null,
      "IsInheritable": null,
      "ExpenseTypes": [
        {
          "Code": "LODNG",
          "Name": "Hotel",
          "ExpenseCode": "LODGING"
        },
        {
          "Code": "LODTX",
          "Name": "Hotel Tax",
          "ExpenseCode": "LODGING"
        },
        {
          "Code": "LNDRY",
          "Name": "Laundry",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "AIRFR",
          "Name": "Airfare",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "01026",
          "Name": "Airline Fees",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "01002",
          "Name": "Car Maintenance/Repairs ",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "CARRT",
          "Name": "Car Rental",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "GASXX",
          "Name": "Fuel",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "PARKG",
          "Name": "Parking",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "MILEG",
          "Name": "Personal Car Mileage",
          "ExpenseCode": "PCARMILE"
        },
        {
          "Code": "TRAIN",
          "Name": "Public Transport",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "TAXIX",
          "Name": "Taxi",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "TOLLS",
          "Name": "Tolls/Road Charges",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "01025",
          "Name": "Train",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "01043",
          "Name": "Alcoholic Beverages & Softs Drinks",
          "ExpenseCode": "MEALS"
        },
        {
          "Code": "BRKFT",
          "Name": "Breakfast",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "DINNR",
          "Name": "Dinner",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "01028",
          "Name": "Individual Meals",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "01044",
          "Name": "Individual Meals - Within Municipality",
          "ExpenseCode": "MEALS"
        },
        {
          "Code": "LUNCH",
          "Name": "Lunch",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "BUSML",
          "Name": "Entertainment - Clients",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "01004",
          "Name": "Entertainment - Staff",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "01005",
          "Name": "Courier/Shipping/Freight",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "OFCSP",
          "Name": "Office Equipment/Hardware",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "POSTG",
          "Name": "Postage",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "01006",
          "Name": "Printing/Photocopying/Stationery",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "01035",
          "Name": "Business Calls",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "ONLIN",
          "Name": "Internet/Online Fees",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "CELPH",
          "Name": "Mobile/Cellular Phone",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "01036",
          "Name": "Non-Business Calls",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "LOCPH",
          "Name": "Telephone/Fax",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "BANKF",
          "Name": "Bank Fees",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "01024",
          "Name": "Currency Exchange Fees",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "01008",
          "Name": "Passports/Visa Fees",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "AWRDS",
          "Name": "Gifts - Clients",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "GIFTS",
          "Name": "Gifts - Staff",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "TRDSH",
          "Name": "Marketing/Promotional Costs",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "01014",
          "Name": "Newspapers/Magazines/Books",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "DUESX",
          "Name": "Professional Subscriptions/Dues",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "SEMNR",
          "Name": "Seminar/Course fees",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "01009",
          "Name": "Tips/Gratuities",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "01012",
          "Name": "Tuition/Training Reimbursement",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "01045",
          "Name": "Undocumented Incidentals - Domestic",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "01046",
          "Name": "Undocumented Incidentals - International",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "CSHRN",
          "Name": "Cash Advance Return",
          "ExpenseCode": "OTHERNP"
        },
        {
          "Code": "CURGL",
          "Name": "Currency Gain/Loss",
          "ExpenseCode": "OTHERNP"
        }
      ]
    },
    {
      "ID": "gWmINGEAkQoapyOLKfSdm0A9qK0ZVUvwolA",
      "Name": "US Expense Policy",
      "IsDefault": null,
      "IsInheritable": null,
      "ExpenseTypes": [
        {
          "Code": "LODNG",
          "Name": "Hotel",
          "ExpenseCode": "LODGING"
        },
        {
          "Code": "LODTX",
          "Name": "Hotel Tax",
          "ExpenseCode": "LODGING"
        },
        {
          "Code": "INCTS",
          "Name": "Incidentals",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "LNDRY",
          "Name": "Laundry",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "01057",
          "Name": "Test4",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "AIRFR",
          "Name": "Airfare",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "01026",
          "Name": "Airline Fees",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "01002",
          "Name": "Car Maintenance/Repairs ",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "CARRT",
          "Name": "Car Rental",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "CARMI",
          "Name": "Company Car Mileage",
          "ExpenseCode": "COCARMILE"
        },
        {
          "Code": "GASXX",
          "Name": "Fuel",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "PARKG",
          "Name": "Parking",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "MILEG",
          "Name": "Personal Car Mileage",
          "ExpenseCode": "PCARMILE"
        },
        {
          "Code": "TRAIN",
          "Name": "Public Transport",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "TAXIX",
          "Name": "Taxi",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "TOLLS",
          "Name": "Tolls/Road Charges",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "01025",
          "Name": "Train",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "BRKFT",
          "Name": "Breakfast",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "01027",
          "Name": "Business Meals (Attendees)",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "DINNR",
          "Name": "Dinner",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "LUNCH",
          "Name": "Lunch",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "BUSML",
          "Name": "Entertainment - Clients",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "01004",
          "Name": "Entertainment - Staff",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "01005",
          "Name": "Courier/Shipping/Freight",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "OFCSP",
          "Name": "Office Equipment/Hardware",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "01007",
          "Name": "Office Supplies/Software",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "POSTG",
          "Name": "Postage",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "01006",
          "Name": "Printing/Photocopying/Stationery",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "01035",
          "Name": "Business Calls",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "ONLIN",
          "Name": "Internet/Online Fees",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "CELPH",
          "Name": "Mobile/Cellular Phone",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "01036",
          "Name": "Non-Business Calls",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "LOCPH",
          "Name": "Telephone/Fax",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "01047",
          "Name": "Agency Booking Fees",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "BANKF",
          "Name": "Bank Fees",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "01024",
          "Name": "Currency Exchange Fees",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "01008",
          "Name": "Passports/Visa Fees",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "AWRDS",
          "Name": "Gifts - Clients",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "GIFTS",
          "Name": "Gifts - Staff",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "TRDSH",
          "Name": "Marketing/Promotional Costs",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "MISCL",
          "Name": "Miscellaneous",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "01014",
          "Name": "Newspapers/Magazines/Books",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "DUESX",
          "Name": "Professional Subscriptions/Dues",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "SEMNR",
          "Name": "Seminar/Course fees",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "01038",
          "Name": "Staff Awards/Incentives",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "01009",
          "Name": "Tips/Gratuities",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "01012",
          "Name": "Tuition/Training Reimbursement",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "CSHRN",
          "Name": "Cash Advance Return",
          "ExpenseCode": "OTHERNP"
        },
        {
          "Code": "CURGL",
          "Name": "Currency Gain/Loss",
          "ExpenseCode": "OTHERNP"
        },
        {
          "Code": "01052",
          "Name": "Fixed Vehicle Reimbursement",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "01053",
          "Name": "Motus Other Amount",
          "ExpenseCode": "OTHER"
        },
        {
          "Code": "01054",
          "Name": "Variable Vehicle Reimbursement",
          "ExpenseCode": "OTHER"
        }
      ]
    }
  ],
  "AttendeeTypes": [
    {
      "Code": "PRIVATE",
      "Name": "Attendee-Private List"
    },
    {
      "Code": "HCOCGDM",
      "Name": "Cegedim HCO Search–OneKey US"
    }
  ],
  "ID": "gWv5bj$sPY1weV9audTTRp7PkBlea3Y6aizg",
  "URI": "https://www.concursolutions.com/api/v3.0/expense/expensegroupconfigurations/gWv5bj$sPY1weV9audTTRp7PkBlea3Y6aizg"
}

Itemizations

Version

3.0 Note that some methods are deprecated

1.1 documentation is available here

Retrieve all expense itemizations owned by the user

DEPRECATED: 05/19/2016 UNSUPPORTED: 11/19/2016

GET /api/v3.0/expense/itemizations

Parameters

Name Type Format Description
reportID string query The report ID of the itemizations to be retrieved. Use the GET /expense/reportdigests function to find the report ID. Format: An alpha-numeric string
entryID string query The entry ID for the itemizations to be retrieved. Use the GET /expense/entries endpoint to learn the valid entry ID.
expenseTypeCode string query The expense type code for the itemizations to be retrieved.
offset string query The starting point of the next set of results, after the limit specified in the limit field has been reached.
limit Int32 query The number of records to return. Default value: 25
user string query The login ID of the user who owns the itemizations. The user must have the Web Services Admin role to use this parameter.

Request URL

https://www.concursolutions.com/api/v3.0/expense/itemizations?limit=10&user=ALL

JSON example of a successful response

{
  "Items": [
    {
      "EntryID": "gWidFO7ikXSy55WZOaAXv8JRfFkruCwrP4g",
      "ReportID": "F4F027007E814C1CA70E",
      "ReportOwnerID": "CAtraveler@concurconnect2.com",
      "ExpenseTypeCode": "LODTX",
      "ExpenseTypeName": "Hotel Tax",
      "SpendCategoryCode": "LODGA",
      "SpendCategoryName": "Lodging - Track Room Rate Spending",
      "TransactionDate": "2013-08-07T00:00:00",
      "TransactionAmount": 20,
      "PostedAmount": 20,
      "ApprovedAmount": 20,
      "LocationID": "gWqWg2EhaUtcIW$s2pMbTGM8W81u2qcfX94w",
      "LocationName": "Montreal, Quebec",
      "LocationSubdivision": "Quebec",
      "LocationCountry": "CA",
      "Description": "test",
      "IsPersonal": false,
      "IsBillable": false,
      "IsImageRequired": false,
      "AllocationType": "N",
      "HasComments": false,
      "HasExceptions": false,
      "LastModified": "2013-09-02T19:40:48.877",
      "OrgUnit1": null,
      "OrgUnit2": null,
      "OrgUnit3": null,
      "OrgUnit4": null,
      "OrgUnit5": null,
      "OrgUnit6": null,
      "Custom1": null,
      "Custom2": null,
      "Custom3": null,
      "Custom4": null,
      "Custom5": null,
      "Custom6": null,
      "Custom7": null,
      "Custom8": null,
      "Custom9": null,
      "Custom10": null,
      "Custom11": null,
      "Custom12": null,
      "Custom13": null,
      "Custom14": null,
      "Custom15": null,
      "Custom16": null,
      "Custom17": null,
      "Custom18": null,
      "Custom19": null,
      "Custom20": null,
      "Custom21": null,
      "Custom22": null,
      "Custom23": null,
      "Custom24": null,
      "Custom25": null,
      "Custom26": null,
      "Custom27": null,
      "Custom28": null,
      "Custom29": null,
      "Custom30": null,
      "Custom31": null,
      "Custom32": null,
      "Custom33": null,
      "Custom34": null,
      "Custom35": null,
      "Custom36": null,
      "Custom37": null,
      "Custom38": null,
      "Custom39": null,
      "Custom40": null,
      "ID": "gWidFO7ikXSy$seMkLiQismjUIYkxYzCsf4g",
      "URI": "https://www.concursolutions.com/api/v3.0/expense/itemizations/gWidFO7ikXSy$seMkLiQismjUIYkxYzCsf4g"
    }
  ]
}

Retrieve an expense itemization by ID

GET /api/v3.0/expense/itemizations/{id}

Parameters

Name Type Format Description
id string path Required The ID of the expense itemization.
user string query The login ID of the user who owns the itemizations. The user must have the Web Services Admin role to use this parameter.

Request URL

https://www.concursolutions.com/api/v3.0/expense/itemizations/gWidFO7ikXV6%24pcZsso2aBN0Aad4P5i8bjCg

JSON example of a successful response

{
  "EntryID": "gWidFO7ikXV6$sQxTtWGQsIhawC4KoyssTCg",
  "ReportID": "39BD9F7C5C3F4986A6A5",
  "ReportOwnerID": "jimadmin@concurconnect2.com",
  "ExpenseTypeCode": "LODTX",
  "ExpenseTypeName": "Hotel Tax",
  "SpendCategoryCode": "LODGA",
  "SpendCategoryName": "Lodging - Track Room Rate Spending",
  "TransactionDate": "2016-04-21T00:00:00",
  "TransactionAmount": 20,
  "PostedAmount": 20,
  "ApprovedAmount": 20,
  "LocationID": "gWqWg2EhcUKB$sottpx8eODvjn1$pWvWfG15A",
  "LocationName": "Bellevue, Washington",
  "LocationSubdivision": "Washington",
  "LocationCountry": "US",
  "Description": null,
  "IsPersonal": false,
  "IsBillable": false,
  "IsImageRequired": false,
  "AllocationType": "N",
  "HasComments": false,
  "HasExceptions": false,
  "LastModified": "2016-04-22T22:19:55.213",
  "OrgUnit1": null,
  "OrgUnit2": null,
  "OrgUnit3": null,
  "OrgUnit4": null,
  "OrgUnit5": null,
  "OrgUnit6": null,
  "Custom1": null,
  "Custom2": null,
  "Custom3": null,
  "Custom4": null,
  "Custom5": null,
  "Custom6": null,
  "Custom7": null,
  "Custom8": null,
  "Custom9": null,
  "Custom10": null,
  "Custom11": null,
  "Custom12": null,
  "Custom13": null,
  "Custom14": null,
  "Custom15": null,
  "Custom16": null,
  "Custom17": null,
  "Custom18": null,
  "Custom19": null,
  "Custom20": null,
  "Custom21": null,
  "Custom22": null,
  "Custom23": null,
  "Custom24": null,
  "Custom25": null,
  "Custom26": null,
  "Custom27": null,
  "Custom28": null,
  "Custom29": null,
  "Custom30": null,
  "Custom31": null,
  "Custom32": null,
  "Custom33": null,
  "Custom34": null,
  "Custom35": null,
  "Custom36": null,
  "Custom37": null,
  "Custom38": null,
  "Custom39": null,
  "Custom40": null,
  "ID": "gWidFO7ikXV6$pcZsso2aBN0Aad4P5i8bjCg",
  "URI": "https://www.concursolutions.com/api/v3.0/expense/itemizations/gWidFO7ikXV6$pcZsso2aBN0Aad4P5i8bjCg"
}

Create a new expense itemization

POST /api/v3.0/expense/itemizations

Parameters

Name Type Format Description
content - body Required The expense itemization object to create.

Request URL

https://www.concursolutions.com/api/v3.0/expense/itemizations

JSON example of a successful response

{
  "ID": "gWidFO7ikXV69FISvVWPbHe1Oj4FbCd0DCg",
  "URI": "https://www.concursolutions.com/api/v3.0/expense/itemizations/gWidFO7ikXV69FISvVWPbHe1Oj4FbCd0DCg"
}

Update an expense itemization

DEPRECATED: 05/19/2016 UNSUPPORTED: 11/19/2016

PUT /api/v3.0/expense/itemizations/{id}

Parameters

Name Type Format Description
id string path Required The ID of the expense itemization
content - body Required The partial or complete expense itemization object to update.

Request URL

https://www.concursolutions.com/api/v3.0/expense/itemizations/gWidFO7ikXV6%24pcZsso2aBN0Aad4P5i8bjCg

JSON example of a successful response

no content

Delete an expense itemization

DEPRECATED: 05/19/2016 UNSUPPORTED: 11/19/2016

DELETE /api/v3.0/expense/itemizations/{id}

Parameters

Name Type Format Description
id string path Required The ID of the expense itemization to delete.
user string query Required The login ID of the user who owns the itemizations. The user must have the Web Services Admin role to use this parameter.

Request URL

https://www.concursolutions.com/api/v3.0/expense/itemizations/gWidFO7ikXV6%24pcZsso2aBN0Aad4P5i8bjCg

JSON example of a successful response

no content

Itemizations - Schema

Itemizations

Name Type Format Description
Items array Itemization The result collection.
NextPage string - The URI of the next page of results, if any.

Itemization

Name Type Format Description
AllocationType string - The type of allocation for the itemization. Possible values: P - partial allocation, F - full allocation, N - no allocation. Use the GET /expense/allocations function to get information about this entry's allocations.
ApprovedAmount Decimal - The approved amount of the expense itemization, in the report currency.
Custom1 through Custom40 CustomField - The details from the Custom fields. These fields may not have data, depending on the configuration. If the form field is configured as a List data type, the value will be the item code for this list. Use the GET /common/listitems operation to learn the item name. Maximum length: 64 characters
Description string - The description of the expense. Maximum length: 64 characters
EntryID string - Required The ID of the expense entry that is the parent for the itemization. Use the GET /expense/entries endpoint to learn the entry ID for the expense itemizations.
ExpenseTypeCode string - Required The code for the expense type. Use the GET /expense/expensegroupconfigurations endpoint to learn the expense type code for expense types that are active for this report's policy.
ExpenseTypeName string - Required The name of the expense type, localized to the user's language.
HasComments Boolean - Indicates whether the expense has comments. Use the GET ExpenseEntryComments endpoint to get information about this entry's comments. Format: true or false
HasExceptions Boolean - Indicates whether the expense has exceptions. Format: true or false
ID string - The unique identifier of the resource.
IsBillable Boolean - Indicates whether the itemization is billable. Format: true or false
IsImageRequired Boolean - Indicates whether a receipt image is required for the entry. Format: true or false
IsPersonal Boolean - Indicates whether the itemization is personal (that is, non-reimbursable). Format: true or false
LastModified DateTime - The UTC date when the itemization was last modified.
LocationCountry string - The country where the expense was incurred. Format: 2-letter ISO 3166-1 country code
LocationID string - The unique identifier for the location where the expense was incurred. Use the GET /common/locations function to get information for this location.
LocationName string - The location where the expense was incurred, usually the city name.
LocationSubdivision string - The state, province, or other country subdivision where the expense was incurred. Format: ISO 3166-2:2007 country subdivision
OrgUnit1 through OrgUnit6 CustomField - The details from the Org Unit fields. These fields may not have data, depending on the configuration. If the form field is configured as a List data type, the value will be the item code for this list. Use the GET /common/listitems operation to learn the item name. Maximum length: 64 characters
PostedAmount Decimal - The amount of the expense itemization, in the report currency.
ReportID string - Required The ID of the report that is the parent for the itemization. Use the GET /expense/reportdigests endpoint to learn the report ID for the itemizations.
ReportOwnerID string - Required The login ID for the report owner. Use the GET User Information endpoint to learn details about this user.
SpendCategoryCode string - Required The code for the spending category that is specified for this itemization.
SpendCategoryName string - Required The name of the spending category that is specified for this itemization, localized to the user's language.
TransactionAmount Decimal - The amount of the expense itemization, in the transaction currency of the parent expense entry.
TransactionDate DateTime - Required The date when the good or service associated with this itemization was provided. Format: YYYY-MM-DD
URI string - The URI to the resource.

Custom Field

Name Type Format Description
Code string - For list fields, this is the list item code.
ListItemID string - For list fields, this is the list item ID.
Type string - The custom field type. Possible values: Amount, Boolean, ConnectedList, Date, Integer, List, Number, Text
Value string - The value in the Org Unit or Custom field. For list fields, this is the name of the list item. Maximum length: 48 characters

Integration Status

The integration status of the supplied object. Currently supports expense reports.

This resource allows developers to ensure that the necessary transactions to account for expenses and arrange payment for the expenses in a specified report were created in the financial system prior to committing the expense report in Concur Expense. If they were, the developer uses this function to indicate the report was successfully integrated and move the report forward in the workflow to the Paid step. In Concur Expense, when a report arrives at the Paid workflow step the report is committed, meaning its data can't be changed and it can't be sent back in the workflow.

URI

https://www.concursolutions.com/api/expense/expensereport/v2.0/integrationstatus/

Operations

POST

Integration Status - Request

Request Parameters

Path Parameters

Parameter Required/Optional Description
report/{ReportID} required The report keyword and the ReportID for the report that has been successfully integrated into the financial system. The ReportID is returned in the ReportID element by the Get List of Reports and the Get Report Details responses.

Headers

Authorization Header

Authorization header with OAuth token for valid SAP Concur user. Required. The OAuth consumer must have the following user role: Web Services Administrator

Content-Type Header

Integration Status - Response

Content Types

Integration Status - Schema

The response will include an ActionStatus parent element (XML), or an object (JSON) with the following child elements (XML) or name/value pairs (JSON).

ActionStatus elements

Element Description
Status Whether the request was successful. Possible values: SUCCESS, FAILURE.
Message Provides further details for errors.

Integration Status - Examples

XML Example Request

POST https://www.concursolutions.com/api/expense/expensereport/v2.0/integrationstatus/report/nx2WRNzp18$wjehk%wqEL6EDHRwi9r$paQS1UqyL6a454QitqQ HTTP/1.1
Authorization: OAuth {access token}
Accept: application/xml
...

XML Example of Successful Response

HTTP/1.1 200 OK
Content-Type: application/xml

<ActionStatus xmlns="http://www.concursolutions.com/api/expense/expensereport/2011/03" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
    <Message>SUCCESS</Message>
    <Status>SUCCESS</Status>
</ActionStatus>

JSON Example of Successful Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "Status": "SUCCESS",
  "Message": "SUCCESS"
}

JSON Example of Response with Error

HTTP/1.1 200 OK
Content-Type: application/json

{
  "Status": "FAILURE",
  "Message": "To use the POST Expense Journal Entry Job Key the report must be at the Processing Payment or Payment Confirmed Payment Status."
}

Create an exception to a report

Posts an exception to the report, and associates it with one of the following data levels: Report Header, Entry, Itemization, Allocation. This endpoint requires familiarity with the company's exception code configuration.

Create an exception to a report - Request

Request Parameters

Path Parameters

Parameter Required/Optional Description
{reportKey}/Exceptions required The identifier for the desired report and the exceptions keyword.

Example: https://www.concursolutions.com/api/expense/expensereport/v1.1/report/{reportKey}/Exceptions

URI Source: The reportKey value is returned in the RptKey element by the Get Report Details response.

Headers

Authorization Header

Authorization header with OAuth token for valid SAP Concur user. Required.

Content-Type Header

application/xml

Create an exception to a report - Request Schema

This request should contain an Exceptions parent element with an Exception parent element for each exception included in the report. The Exception element contains the following child elements:

Exception Elements

Element Required (must contain value)? Description
Index Y The exception's location in a batch of exceptions. Should start at 1 and increment sequentially. This value is used to identify the record if there is an error.
ObjectType Y The type of object to assign the exception. Format: Report, Entry, or Allocation. When sending a Report level exception, the ObjectType and ObjectId can be null, as the report key is supplied in the URI.
ObjectId Y The unique identifier for the object to associate with the exception. Returned by the Get Report Details function. Must be the value from one of the following fields:
   Entry or Itemization: Use the RpeKey.
   Allocation: Use AllocationKey.
   Report Header: Null value. When sending a Report level exception, the ObjectType and ObjectId can be null, as the report key is supplied in the URI.
ExceptionCode Y The Exception Code for the exception to assign to the object. Must be a configured exception code in Expense. Example: NODATE

Create an exception to a report - Response

Content Types

application/xml

Create an exception to a report - Response Schema

This request will return an exception-result parent element.

Exception-Result Elements

Element Description
exceptions-succeeded The number of exceptions processed that were successfully assigned.
exceptions-failed The number of exceptions processed that were not successfully added.
errors This will contain an error parent element for each record failure. The error element will contain the following child elements:
   Index: The exception's location in the batch.
   message: The error message.
ExceptionDetails This parent element will contain an ExceptionInfo parent element for all exceptions that did not cause an error, and will contain the following child elements:
   Index: The exception's location in the batch.
   Status: The status of the request.

Create an exception to a report - Examples

XML Example Request

POST https://www.concursolutions.com/api/expense/expensereport/v1.1/report/3FK118eIJ844Uwl0HF32/Exceptions HTTP/1.1
Authorization: OAuth {access token}
Content-Type: application/xml

<Exceptions xmlns="http://www.concursolutions.com/api/expense/expensereport/2011/03" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
    <Exception>
        <Index>1</Index>
        <ObjectType>Report</ObjectType>
        <ObjectId>nxxKgLlnRODp$sie8Hq1UviOJ2AbpS7dCP</ObjectId>
        <ExceptionCode>APPRVTO</ExceptionCode>
    </Exception>
    <Exception>
        <Index>2</Index>
        <ObjectType>Entry</ObjectType>
        <ObjectId>nxxKgLlnRODp$sie8Hq1UviOJ2deAbpS7dC0</ObjectId>
        <ExceptionCode>APPRVTO</ExceptionCode>
    </Exception>
</Exceptions>

XML Example of Response With Success and Failure

<exception-result xmlns="http://www.concursolutions.com/api/expense/expensereport/2011/03" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
    <exceptions-succeeded>1</exceptions-succeeded>
    <exceptions-failed>1</exceptions-failed>
    <errors>
        <error>
            <Index>2</Index>
            <message>Invalid Exception Code</message>
        </error>
    </errors>
    <ExceptionDetails>
        <ExceptionInfo>
            <Index>1</Index>
            <Status>Success</Status>
        </ExceptionInfo>
    </ExceptionDetails>
</exception-result>

Submit an expense report

Triggers the Submit workflow action for the specified report.

Important Note: This endpoint submits the expense report as if the original report owner had submitted it. Consult your company's Expense administrator to confirm that the web service should be allowed to submit reports on behalf of users. If you wish to enforce the expense report delegate functionality, use the Get Expense Delegators function to determine if the user in question has the correct permissions to submit on behalf of the report owner.

Submit An Expense Report - Request

Request Parameters

Path Parameters

Parameter Required/Optional Description
{reportKEY}/submit required The identifier for the desired report and the submit keyword.

Example: https://www.concursolutions.com/api/expense/expensereport/v1.1/report/{reportKEY}/submit

URI Source: The reportId value is returned by the Get List of Reports and Get Report Details functions, and as part of the Report-Details-Url element of the Post Expense Report Header function.

Content Types

application/xml

Authorization Header

Authorization: This request requires an Authorization header with an OAuth token for a valid SAP Concur user.

X_UserID: This request requires an additional field in the authorization header, identifying the report owner. This identifier is the SAP Concur login for the user, and is often also the email address of the user. The field format is:
X_UserID: expenseuser@example.com

Submit An Expense Report - Response

Submit An Expense Report - Schema

This request will return a ReportStatus parent element with the following child elements.

Report Status Elements

Element Description
Message The error message. Only appears if a submission error was generated.
Status The status of the report submit action.

If the report submission triggered an exception, a ReportExceptions parent element will be provided, with a ReportException parent element for each exception. The ReportException element contains the following elements.

Report Exception Schema

Element Description
CrnCode The currency code of the entry.
EventCode The event that resulted in the exception.
ExceptionCode The company-defined exception code.
ExceptionErrorCode The severity of the exception. Exceptions with ERROR as the code cannot be submitted.
ExceptionVisibility Which users are able to see the exception.
ExpKey The expense type key for the entry.
ExpName The expense type name for the entry.
IsCleared Whether the exception has been cleared by the Expense Processor.
SeverityLevel A numeric value indicating the severity level of the exception. The value threshold is configurable.
TransactionAmount The amount of the entry.
TransactionDate The date of the entry.
Type The exception type.

Submit An Expense Report - Examples

XML Example Request

POST https://www.concursolutions.com/api/expense/expensereport/v1.1/report/nxxKgLlnROz$sQ6SKJFjLNs4OWBErcJ8yX/submit HTTP/1.1
Authorization: OAuth {access token}
X-UserID: cmiller@example.com
...

XML example of Successful Response

<ReportStatus xmlns="http://www.concursolutions.com/api/expense/expensereport/2011/03" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
    <Status>SUCCESS</Status>
</ReportStatus>

Post an expense report workflow action

Posts a workflow action for the supplied expense report. The workflow action moves the expense report through the workflow process.

Workflow Actions

The available actions are:

WARNING: Prior to calling this endpoint the Caller must check the Approval Status found in the ApprovalStatusName element in the response for Get Report Details to ensure the report is at the workflow step the Caller expects.  Under no circumstance should a Caller make a call to this endpoint without being certain the report is at the workflow step the Caller expects.

Workflow Roles

Each workflow step in a workflow is associated with a workflow role. Professional clients can configure workflow steps and roles in the Workflows area of Expense Admin. The OAuth consumer is evaluated to determine which role(s) the consumer has in SAP Concur. There are two different types of workflow roles as described in the following sections.

System Role

The System role is used when the workflow actions can be completed programatically. Any workflow action can be completed this way, depending on the client's business process. The workflow role can be configured while adding the report workflow step. Some steps may require the System role. When using this role, the OAuth consumer must have the following user role:

The expense report owner must have an approver or processor assigned to them before the System role can make changes to their reports.

Approver Role

The Approver role is used when the workflow action should be completed by a particular user. Developers who want to present a list of reports to approve and send the workflow action when the reports have been evaluated by the approver use the Approver role. This role requires that a user with the correct SAP Concur role (Expense Approver, Authorized Approver, Cost Object Approver, or Expense Processor for Professional, or the Can Administer or Can Approve Reports roles for Standard) authenticates using Standard OAuth before supplying the workflow action. The user must also have access (be a valid approver or processor) for the supplied report ID.

Post an expense report workflow action - Request

Request Parameters

Path Parameters

Parameter Required/Optional Description
{workflowstepID}/workflowaction required The identifier for the desired workflow step and the workflowaction keyword.

Example: https://www.concursolutions.com/api/expense/expensereport/v1.1/report/{workflowstepId}/workflowaction

URI Source: The URI is returned in the WorkflowActionURL element of the Get Report Details response.

Headers

Authorization Header

Authorization header with OAuth token for valid SAP Concur user. Required.

Content-Type Header

application/xml

Request Body

Post an expense report workflow action - Request Schema

This request should contain a WorkflowAction parent element with the following child elements.

WorkflowAction Child Elements

Element Required/optional Description
Action required The name of the workflow action. Possible values are: Approve, Send Back to Employee, or Recall to Employee. Must be one of the workflow actions available for the workflow step. Consult Expense Admin > Workflow to learn details.
Comment required, for Send Back to Employee Must be used with the Send Back to Employee workflow action. This comment is visible wherever report comments are available to the employee, approver, authorization request administrator, and/or processor. Max length: 2000

Post an expense report workflow action - Response

Post an expense report workflow action - Response Schema

This request will return an ActionStatus parent element with the following child elements.

ActionStatus Elements

Element Description
Message The error message. Only appears if a workflow action error was generated.
Status The status of the report workflow action.

Post an expense report workflow action - Examples

XML Example Request

POST https://www.concursolutions.com/api/expense/expensereport/v1.1/report/nx2WRNzp18$wjehk%wqEL6EDHRwi9r$paQS1UqyL6a454QitqQ/workflowaction HTTP/1.1
Authorization: OAuth {access token}
...

<WorkflowAction xmlns="http://www.concursolutions.com/api/expense/expensereport/2011/03">
    <Action>Approve</Action>
    <Comment>Approved via SAP Concur</Comment>
</WorkflowAction>

XML Example of Successful Response

<?xml version="1.0" encoding="utf-8"?>
<ActionStatus xmlns="http://www.concursolutions.com/api/expense/expensereport/2011/03" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
    <Message>SUCCESS!</Message>
    <Status>SUCCESS!</Status>
</ActionStatus>

XML Example of Response with Error

<?xml version="1.0" encoding="utf-8"?>
<ActionStatus xmlns="http://www.concursolutions.com/api/expense/expensereport/2011/03" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
    <Message>The action cannot be executed because the item has recently been changed. Please refresh your list and try again.</Message>
    <Status>FAILURE</Status>
</ActionStatus>

Reports v3

Prior Versions

Retrieve reports owned by the user based on search criteria

GET  /api/v3.0/expense/reports

Parameters

Name Type Format Description
offset string query Starting page offset
limit Int32 query Number of records to return (default 25)
user string query Optional. The login ID of the report owner(s) to use when searching for reports. If the value is set to LoginID, reports for the report owner with this login ID value are returned. If the value is set to ALL, reports for all report owners are returned. If this parameter is not specified, reports for the OAuth Consumer are returned. The access token owner (OAuth Consumer) must have the Web Services Admin role to use this parameter.
approvalStatusCode string query The status code for the Approval Status. The values can include Concur Expense standard codes or custom codes. The Concur Expense standard code values are: A_AAFH - Report submission triggered an anomaly and fraud check; A_ACCO - Report is pending reviews; A_APPR - Report has been approved; A_EXTV - Report is pending external validation; A_FILE - Report has been submitted; A_NOTF - Report has not been submitted; A_PBDG - Report approval is pending Budget approval; A_PECO - Report approval is pending Cost object approval; A_PEND - Report is pending manager approval; A_PVAL - Report is pending prepayment validation; A_RESU - Report needs to be resubmitted; A_RHLD - Report submission is pending receipt images; A_TEXP - Report expired in approval queue. For custom codes, contact Concur Developer Support.
paymentStatusCode string query The payment status code for the report. The values can include Concur Expense standard codes or custom codes. The Concur Expense standard code values are: P_HOLD - Report payment is on hold; P_NOTP - Report has not been paid; P_PAID - Report has been paid; P_PAYC - Payment is confirmed. Some or all of the report expenses have been paid; P_PROC - Report is in process to be paid. For custom codes, contact Concur Developer Support.
currencyCode string query The 3-letter ISO 4217 currency code for the report currency. Example: USD.
paymentType string query The unique identifier for the payment type that is the payment type for at least one expense entry in the report. Use PaymentTypeID from Response of GET Expense Group Configurations V3 to obtain valid payment types.
reimbursementMethod string query The method the report owner will be reimbursed. VALUES: ADPPAYR - ADP Payroll; APCHECK - AP (Company Check); CNQRPAY - Expense Pay; PMTSERV - Other Payment Service. NOTE: PAY_PAL is NOT supported.
approverLoginID string query The login ID for the report approver that is the current approver assigned to the report.
expenseTypeCode string query The expense type code that is the expense type for at least one expense entry in the report. Use ExpenseTypeCode from Response of GET Expense Group Configurations V3.
attendeeTypeCode string query The report contains expense entries that have attendees of the specified type.
countryCode string query The report country. Maximum 2 characters. Format: The ISO 3166-1 alpha-2 country code. Example: United States is US.
batchID string query The unique identifier for a payment batch where there is at least one report payee within the report. Use the BatchID from Response of GET Payment Batch List.
vendorName string query The Vendor Description that is the vendor for at least one expense entry in the report.
hasVAT Boolean query Determines if the report has at least one expense entry with VAT details. Format: true or false.
hasImages Boolean query Determines if the report has at least one expense entry with an entry image or if there is a report image for this report. Format: true or false.
hasAttendees Boolean query Determines if the report has at least one expense entry with an attendee. Format: true or false.
hasBillableExpenses Boolean query The IsBillable flag for at least one expense entry in the report. Format: true or false.
isTestUser Boolean query The report owner is a test user using the report for testing purposes in a non-production environment. Format: true or false.
expenseGroupConfigID string query The unique identifier for the expense group configuration associated to the report's expense group. Use the ID from the Response of the Expense Group Configurations V3.
entryTransactionDateBefore DateTime query The entry transaction date for at least one expense entry in the report is before this date. Format: YYYY-MM-DD
entryTransactionDateAfter DateTime query The entry transaction date for at least one expense entry in the report is after this date. Format: YYYY-MM-DD
createDateBefore DateTime query The report create date is before this date. Format: YYYY-MM-DD
createDateAfter DateTime query The report create date is after this date. Format: YYYY-MM-DD
userDefinedDateBefore DateTime query The report user defined date is before this date. Format: YYYY-MM-DD
userDefinedDateAfter DateTime query The report user defined date is after this date. Format: YYYY-MM-DD
submitDateBefore DateTime query The report submit date is before this date. Format: YYYY-MM-DD
submitDateAfter DateTime query The report submit date is after this date. Format: YYYY-MM-DD
processingPaymentDateBefore DateTime query The report processing payment date is before this date. Format: YYYY-MM-DD
processingPaymentDateAfter DateTime query The report processing payment date is after this date. Format: YYYY-MM-DD
paidDateBefore DateTime query The report paid date is before this date. Format: YYYY-MM-DD
paidDateAfter DateTime query The report paid date is after this date. Format: YYYY-MM-DD
modifiedDateBefore DateTime query The report modified date is before this date. Format: YYYY-MM-DD
modifiedDateAfter DateTime query The report modified date is after this date. Format: YYYY-MM-DD

Request URL

https://www.concursolutions.com/api/v3.0/expense/reports?limit=15&user=ALL

JSON example of a successful response

{
  "Items": [
    {
      "Name": "Canadian Tax",
      "Total": 1900,
      "CurrencyCode": "CAD",
      "Country": "CA",
      "CountrySubdivision": "CA-BC",
      "CreateDate": "2013-09-02T19:05:57.687",
      "SubmitDate": "2013-09-02T19:18:35.537",
      "ProcessingPaymentDate": "2013-09-02T19:40:48.533",
      "PaidDate": "2013-09-02T19:46:01.57",
      "ReceiptsReceived": false,
      "UserDefinedDate": "2013-09-02T00:00:00",
      "LastComment": "",
      "OwnerLoginID": "CAtraveler@concurconnect2.com",
      "OwnerName": "Canadian Traveler",
      "ApproverLoginID": null,
      "ApproverName": null,
      "ApprovalStatusName": "Approved",
      "ApprovalStatusCode": "A_APPR",
      "PaymentStatusName": "Sent for Payment",
      "PaymentStatusCode": "P_PAID",
      "LastModifiedDate": "2013-09-02T19:46:01.98",
      "PersonalAmount": 0,
      "AmountDueEmployee": 1500,
      "AmountDueCompanyCard": 0,
      "TotalClaimedAmount": 1900,
      "TotalApprovedAmount": 1900,
      "LedgerName": "DEFAULT",
      "PolicyID": "gWmINGEAkQoamAzOARD9NEBtuv0ppnbJ4lQ",
      "EverSentBack": false,
      "HasException": false,
      "WorkflowActionUrl": "http://www.concursolutions.com/api/v3.0/expense/reports/report/gWpkOyRxJoH6lOiUHqNhW93UWxhOZZw/WorkFlowAction?limit=15&user=ALL",
      "OrgUnit1": null,
      "OrgUnit2": null,
      "OrgUnit3": null,
      "OrgUnit4": null,
      "OrgUnit5": null,
      "OrgUnit6": null,
      "Custom1": null,
      "Custom2": null,
      "Custom3": null,
      "Custom4": null,
      "Custom5": null,
      "Custom6": null,
      "Custom7": null,
      "Custom8": null,
      "Custom9": null,
      "Custom10": null,
      "Custom11": null,
      "Custom12": null,
      "Custom13": null,
      "Custom14": null,
      "Custom15": null,
      "Custom16": null,
      "Custom17": null,
      "Custom18": null,
      "Custom19": null,
      "Custom20": null,
      "ID": "F4F027007E814C1CA70E",
      "URI": "https://www.concursolutions.com/api/v3.0/expense/reports/F4F027007E814C1CA70E"
    }
  ]
}

Retrieve a report by ID

GET /api/v3.0/expense/reports/{id}

Parameters

Name Type Format Description
id string path Required Report ID
user string query Optional. The login ID of the report owner(s) to use when searching for reports. If the value is set to LoginID, reports for the report owner with this login ID value are returned. If the value is set to ALL, reports for all report owners are returned. If this parameter is not specified, reports for the OAuth Consumer are returned. The access token owner (OAuth Consumer) must have the Web Services Admin role to use this parameter.

Request URL

https://www.concursolutions.com/api/v3.0/expense/reports/39BD9F7C5C3F4986A6A5

JSON example of a successful response

{
  "Name": "Test 02",
  "Total": 307.01,
  "CurrencyCode": "USD",
  "Country": "US",
  "CountrySubdivision": null,
  "CreateDate": "2016-04-04T23:33:08.21",
  "SubmitDate": null,
  "ProcessingPaymentDate": null,
  "PaidDate": null,
  "ReceiptsReceived": false,
  "UserDefinedDate": "2016-04-04T00:00:00",
  "LastComment": "",
  "OwnerLoginID": "jimadmin@concurconnect2.com",
  "OwnerName": "Jim Admin",
  "ApproverLoginID": null,
  "ApproverName": null,
  "ApprovalStatusName": "Not Submitted",
  "ApprovalStatusCode": "A_NOTF",
  "PaymentStatusName": "Not Paid",
  "PaymentStatusCode": "P_NOTP",
  "LastModifiedDate": "2016-04-23T02:53:23.7",
  "PersonalAmount": 0,
  "AmountDueEmployee": 290,
  "AmountDueCompanyCard": 0,
  "TotalClaimedAmount": 307.01,
  "TotalApprovedAmount": 307.01,
  "LedgerName": "DEFAULT",
  "PolicyID": "gWmINGEAkQoapyOLKfSdm0A9qK0ZVUvwolA",
  "EverSentBack": false,
  "HasException": true,
  "WorkflowActionUrl": "",
  "OrgUnit1": null,
  "OrgUnit2": null,
  "OrgUnit3": null,
  "OrgUnit4": null,
  "OrgUnit5": null,
  "OrgUnit6": null,
  "Custom1": null,
  "Custom2": null,
  "Custom3": null,
  "Custom4": null,
  "Custom5": null,
  "Custom6": null,
  "Custom7": null,
  "Custom8": null,
  "Custom9": null,
  "Custom10": null,
  "Custom11": null,
  "Custom12": null,
  "Custom13": null,
  "Custom14": null,
  "Custom15": null,
  "Custom16": null,
  "Custom17": null,
  "Custom18": null,
  "Custom19": null,
  "Custom20": null,
  "ID": "39BD9F7C5C3F4986A6A5",
  "URI": "http://www.concursolutions.com/api/v3.0/expense/reports/39BD9F7C5C3F4986A6A5"
}

Create a new report

Note: Expense reports will be created under the user's default expense policy. If a user has two expense policies - default and purchasing card - passing the PolicyKey on the post body will be ignored by Expense. That is, the expense report will always be under the default expense policy.

POST /api/v3.0/expense/reports

Parameters

Name Type Format Description
content - body Required Report object to create

Update a report

Request URL

https://www.concursolutions.com/api/v3.0/expense/reports

JSON example of a successful response

{
  "ID": "DD683A53018A4349B7CD",
  "URI": "https://www.concursolutions.com/api/v3.0/expense/reports/DD683A53018A4349B7CD"
}

PUT /api/v3.0/expense/reports/{id}

Parameters

Name Type Format Description
id string path Required The unique identifier for the report.
content body Required The report object to update

Reports v3 - Schema

Reports

Name Type Format Description
Items array Report The result collection.
NextPage string - The URI of the next page of results, if any.

Report

Name Type Format Description
AmountDueCompanyCard Decimal - The total amount due to the company card for the report. Maximum 23 characters.
AmountDueEmployee Decimal - The total amount due to the employee for the report. Maximum 23 characters.
ApprovalStatusCode string - The approval status code for the report.
ApprovalStatusName string - The report's approval status, in the OAuth consumer's language.
ApproverLoginID string - The Login ID of the report owner's expense approver.
ApproverName string - The name of the report owner's expense approver.
Country string - The report country. Maximum 2 characters. Format: The ISO 3166-1 alpha-2 country code. Example: United States is US.
CountrySubdivision string - The report country subdivision. Format: ISO 3166-2:2007 country subdivision.
CreateDate DateTime - The date the report was created.
CurrencyCode string - The 3-letter ISO 4217 currency code for the expense report currency. Examples: USD - US dollars; BRL - Brazilian real; CAD - Canadian dollar; CHF - Swiss franc; EUR - Euro; GBO - Pound sterling; HKD - Hong Kong dollar; INR - Indian rupee; MXN - Mexican peso; NOK - Norwegian krone; SEK - Swedish krona.
Custom1 thorugh Custom20 CustomField - The details from the Custom fields. These may not have data, depending on configuration.
EverSentBack Boolean - Whether the report has ever been sent back to the employee. Format: Y/N
HasException Boolean - Whether the report has exceptions. Format: Y/N
ID string - The unique identifier of the resource.
LastComment string - The text of the most recent comment on the report.
LastModifiedDate DateTime - The date the report header was last modified.
LedgerName string - The name of the expense report ledger. Maximum 20 characters.
Name string - Required The name of the report.
OrgUnit1 through OrgUnit6 CustomField - The details from the Org Unit fields. These may not have data, depending on configuration.
OwnerLoginID string - The Login ID of the user this report belongs to.
OwnerName string - The name of the expense report owner.
PaidDate DateTime - The date when all journal entries in the report was integrated with or extracted to the financial system.
PaymentStatusCode string - The code for the payment status of the report.
PaymentStatusName string - The report's payment status, in the OAuth consumer's language.
PersonalAmount Decimal - The total amount of expenses marked as personal. Maximum 23 characters.
PolicyID string - The unique identifier of the policy that applies to this report. Maximum 64 characters. User's default expense policy is being used when creating a new expense report
ProcessingPaymentDate DateTime - The date that the report completed all approvals and was ready to be extracted for payment.
ReceiptsReceived Boolean - If Y, then this entry has been marked as confirmed by the Expense Processor. Format: Y/N
SubmitDate DateTime - The date the report was submitted.
Total Decimal - The total amount of the report.
TotalApprovedAmount Decimal - The total amount of approved expenses in the report. Maximum 23 characters.
TotalClaimedAmount Decimal - The total amount of all non-personal expenses in the report. Maximum 23 characters.
URI string - The URI to the resource.
UserDefinedDate DateTime - The date of the report assigned by the user.
WorkflowActionUrl string - The URL to post a workflow action to the report using the Post Report Workflow Action function.

Custom Field

Name Type Format Description
Code string - For list fields, this is the list item code.
ListItemID string - For list fields, this is the list item ID.
Type string - The custom field type. Possible values: Amount, Boolean, ConnectedList, Date, Integer, List, Number, Text
Value string - The value in the Org Unit or Custom field. For list fields, this is the name of the list item. Maximum length: 48 characters

Request URL

https://www.concursolutions.com/api/v3.0/expense/reports/39BD9F7C5C3F4986A6A5

JSON example of a successful response

no content

Report details

Retrieves the full set of information for the report. Includes the Report Header, Entry, Attendee, Itemization and Allocation details.

Some elements will appear only if the OAuth consumer has the Web Services Admin role. These include: The ReportKey element, the employee's credit card information, and the employee's bank account information, VAT information, Journal entries. Connectors that utilize this information go through a review process with SAP Concur that includes verification of secure data handling.

GET list of reports can be found [here]((#reports-v2)

Report Details - Request

Request Parameters

Path Parameters

Parameter Required/Optional Description
reportId required The identifier for the desired report.

Example: https://www.concursolutions.com/api/expense/expensereport/v2.0/report/{reportId}

URI Source: The ReportId is returned in the ReportId element of the Get List of Reports function

Headers

Authorization Header

Authorization header with OAuth token for valid SAP Concur user. The OAuth consumer must have one of the following user roles in SAP Concur: Company Administrator or Web Services Administrator for Professional, or Can Administer for Standard. These roles allow the user to manage data for the entire company.

Accept Header

application/xml

Report Details - Response

Content Types

application/xml

Report Details - Schema

This request will return a ReportDetails parent element.

ReportDetails

Element Description
UserLoginID The user ID of the report owner. Maximum 128 characters.
EmployeeName The name of the employee who created the report. Maximum 66 characters.
ReportID The unique identifier for the report, which appears in the Concur Expense UI. Maximum 32 character varchar.
ReportKey The unencrypted unique identifier for the report, that appears on the report header. The element appears only if the OAuth consumer has the Web Services Admin role in SAP Concur. Maximum 48 characters.
ReportName The name of the report. Maximum 40 characters.
Purpose The information from the Business Purpose field.
ReportDate The date from the report header. Format: YYYY-MM-DDThh:mm:ss
CreationDate The date the report was created. Format: YYYY-MM-DDThh:mm:ss
SubmitDate The date the report was submitted. Maximum 10 characters.
PaidDate The date the report was extracted for payment. This element has an attribute named i:nil. If the value for this element is null, the i:nil attribute will be set to true. Format: YYYY-MM-DDThh:mm:ss
CurrencyCode The 3-letter ISO 4217 currency code for the expense report currency. The expense report currency is defined as the report creator's default reimbursement currency.
ReportTotal The total amount of the report. Maximum 23 characters.
PersonalExpenses The total amount of expenses marked as personal. Maximum 23 characters.
AmountDueEmployee The total amount due to the employee for the report. Maximum 23 characters.
AmountDueCompanyCard The total amount due to the company card for the report. Maximum 23 characters.
TotalClaimedAmount The total amount of all non-personal expenses in the report. Maximum 23 characters.
TotalApprovedAmount The total amount of approved expenses in the report. Maximum 23 characters.
ApprovalStatusCode The approval status code for the report.
ApprovalStatusName The approval status name for the report.
PaymentStatusCode The unique identifier for the payment status of the report.
PaymentStatusName The payment status of the report.
OrgUnit1 through OrgUnit6 The details from the Org Unit custom fields. These may not have data, depending on configuration. Maximum 48 characters for each field.
Custom1 through Custom20 The details from the Custom fields. These may not have data, depending on configuration. If report owner information is stored in these fields, it may be outdated. Refer to the ReportOwner parent element for the current owner information. Refer to the Custom Fields Child Elements table for more information.
LedgerName The name of the expense report ledger. Maximum 20 characters.
PolicyID The unique identifier of the policy that applies to this report. Maximum 64 characters.
EverSentBack Whether the report has ever been sent back to the employee. Format: Y/N
HasException Whether the report has exceptions. Format: Y/N
WorkflowActionURL The URL to post a workflow action to the report using the Post Report Workflow Action function.
ExpenseEntriesList This parent element has an ExpenseEntry child element for each entry. Refer to the ExpenseEntry elements table for more information.
ReportImageURL The URL to access the image associated with the report. This URL is valid for 30 minutes after the web service call.
Country The report country. Maximum 2 characters. Format: The ISO 3166-1 alpha-2 country code. Example: United States is US.
CountrySubdivision The report country subdivision. Format: ISO 3166-2:2007 country subdivision.
ProcessingPaymentDate The date that the report completed all approvals and was ready to be extracted for payment. Format: YYYY-MM-DD
ReceiptsReceived If Y, then this report has its receipt receipt confirmed by the Expense Processor. Format: Y/N
ReportOwner This parent element includes details about the employee who is the report owner. It saves the caller from calling the Get User Information function to get employee information commonly used in accounting integration. The ReportOwner element includes the most recent information about the report owner, at the time the report is requested.
EmployeeBankAccount This parent element includes the bank account data found on the Bank Information page in Profile. This data is used in Payment System integrations where the payment system reimburses the employee via this bank account.

ExpenseEntry

Element Description
ReportEntryID The ID of the report entry. Maximum 13 characters.
ExpenseTypeID The expense type ID for the expense entry. Expense Type IDs are returned in the ExpKey element by the Get Expense Group Configuration endpoint.
ExpenseTypeName The expense type name. Maximum 64 characters.
SpendCategory The spend category specified for this expense type. Varies by client, used in reporting.
PaymentTypeCode The code for the payment type. Maximum 4 characters.
PaymentTypeName The name for the payment type. Maximum 80 characters.
TransactionDate The date of the expense entry. Maximum 10 characters. Format: YYYY-MM-DD
TransactionCurrencyName The name of the transaction currency. Example: US, Dollar
ExchangeRate The exchange rate that applies to the entry. Maximum 23 characters.
TransactionAmount The amount of the expense entry in the original transaction currency. Maximum 23 characters.
PostedAmount The amount of the expense entry in the user's reimbursement currency. The user's reimbursement currency is returned in the CrnCode element for the report. Maximum 23 characters.
ApprovedAmount The approved amount of the expense entry in the user's reimbursement currency.The user's reimbursement currency is returned in the CrnCode element for the report. Maximum 23 characters.
BusinessPurpose The text from the Business Purpose field of the entry. Maximum 64 characters.
VendorDescription The vendor name of the expense entry, which can be entered manually by the user or imported from the card transaction Merchant Name field. Maximum 64 characters.
LocationName The location for the expense entry, usually the city name.
LocationSubdivision The location's State, Province, or Country Subdivision. Maximum 6 characters.
LocationCountry The location's Country. Maximum 2 characters.
OrgUnit1 through OrgUnit6 The details from the Org Unit custom fields. These may not have data, depending on configuration. Maximum 48 characters for each field.
Custom1 through Custom40 The details from the Custom fields. These may not have data, depending on configuration. Refer to the Custom Fields elements table for more information.
FormID The ID for the expense entry form.
EntryImageID The unique identifier for the image associated with the entry.
HasVat Whether the entry contains VAT data. Maximum 1 character. Format: Y/N
HasComments Whether the expense entry has comments. Maximum 1 character. Format: Y/N
CommentCount The number of comments associated with the expense entry.
IsItemized Whether the expense entry is itemized. Maximum 1 character. Format: Y/N
HasExceptions Whether the expense entry has exceptions. Maximum 1 character. Format: Y/N
IsPersonal Whether the expense entry is marked as personal. Maximum 1 character. Format: Y/N
HasAttendees Whether the expense entry has attendees. Maximum 1 character. Format: Y/N
HasAllocation Defines the amount of allocations for the expense. Maximum 1 character. Possible values are: P, for partial allocation, F, for full allocation, or N, for no allocation.
IsCreditCardCharge Whether the expense came from a credit card feed. Maximum 1 character. Format: Y/N
IsPersonalCardCharge Whether the expense came from a personal card feed. Maximum 1 character. Format: Y/N
ReceiptRequired Whether the original receipt is required for the entry. Maximum 1 character. Format: Y/N
ImageRequired Whether a receipt image is required for the entry. Maximum 1 character. Format: Y/N
E-ReceiptID The ID for the attached e-receipt, if available.
LastModifiedDate The date the expense entry was last changed. Maximum 19 characters. Format: YYYY-MM-DDThh:mm:ss
ItemizationsList The list of itemizations for the expense entry. This parent element will have at least one Itemization child element. If the expense entry is not itemized, the Itemization will contain the same values as the entry. If the expense entry has itemizations, there will be one Itemization child element for each itemization. Refer to the Itemization elements table for more information.
NOTE: There are a few rare cases where the ItemizationsList will be null. This happens when a report entry has a payment type code that is not IBCP with offsets or CBCP and there is a Regular or Child expense entry with an Approved Amount equal to zero. The expense entry will have a Null ItemizationsList.
ReportEntryVendorName Vendor name the employee selected from the Vendor list field. Maximum 64 characters.
ReportEntryReceiptReceived If Y, then this entry has been marked as reviewed by a processor. Maximum 1 character. Format: Y/N
ReportEntryReceiptType Maximum 1 character. One of these:
T = tax receipt
R= regular receipt
N = no receipt
CardTransaction This parent element includes the card transaction data found in the card transaction associated to this expense entry. This data is used in Payment System integrations where the payment system reimburses the card issuer for the indicated card account. Refer to the CardTransaction elements table.
ExpensePay Whether the entry was paid using the Expense Pay service. This element has a value if the report has reached the Processing Payment workflow step. Format: Yes/No

Report Details - Itemization

Element Description
ItemType The type of itemization. If the expense entry does not have any itemizations, this will be set to Regular. If the expense entry contains itemizations, each one will be set to Child.
ItemizationID The unique identifier for the itemization. Maximum 19 characters.
ExpenseTypeID The expense type ID for the itemization.
ExpenseTypeName The expense type for the itemization. Maximum 64 characters.
TransactionDate The date of the transaction. Maximum 10 characters. Format: YYYY-MM-DD
TransactionAmount The amount for the itemization in the expense currency. Maximum 23 characters.
PostedAmount The amount for the itemization in the user's reimbursement currency. The user's reimbursement currency is returned in the CrnCode element for the report. Maximum 23 characters.
ApprovedAmount The approved amount of the itemization in the user's reimbursement currency. The user's reimbursement currency is returned in the CrnCode element for the report. Maximum 23 characters.
BusinessPurpose The business purpose field from the report header.
OrgUnit1 through OrgUnit6 The details from the Org Unit custom fields. These may not have data, depending on configuration. Maximum 48 characters for each field.
Custom1 through Custom40 The custom fields associated with the itemization. These may not have data, depending on your configuration. Refer to the Custom Fields elements table for more information.
Value The value in the custom field. Maximum 48 characters.
Code Custom list fields will include the list item code in this element.
HasComments Whether the itemization has comments. Maximum 1 character. Format: Y/N
CommentCount The number of comments associated with the itemization.
IsPersonal Whether the itemization is personal. Maximum 1 character. Format: Y/N
LastModified The UTC date when the itemization was last modified. Maximum 19 characters. Format: YYYY-MM-DDThh:mm:ss
AttendeesList This parent element contains one Attendee element for each associated attendee. Refer to the Attendee elements table for more information.
AllocationsList This parent element contains at least one Allocation element. It will contain multiple Allocation elements if there are multiple allocations for the itemization. Refer to the Allocation elements table.

Report Details - Attendee

Element Description
AttendeeType The type of attendee. Maximum 40 characters.
FirstName The attendee's first name. Maximum 50 characters.
LastName The attendee's last name. Maximum 132 characters.
Company The attendee's company name. Maximum 150 characters.
Title The attendee's title. Maximum 32 characters.
ExternalID The unique identifier for the attendee, managed outside SAP Concur. Maximum 48 characters.
Custom1 through Custom20 The details from the custom fields. These may not have data, depending on configuration. Refer to the Custom Fields elements table for more information.
HasExceptionsPrevYear Whether the attendee has exceptions in the previous year, based on yearly total limits for attendees. Maximum 1 character. Format: Y/N
HasExceptionsYTD Whether the attendee has exceptions in the current year, based on yearly total limits for attendees. Maximum 1 character. Format: Y/N
IsDeleted Whether the attendee is marked as deleted. Maximum 1 character. Format: Y/N
OwnerName The name of the employee that owns the attendee record.
TotalAmountPrevYear The total amount spent on the attendee in the previous calendar year.
TotalAmountYTD The total amount spent on the attendee in the current calendar year.
VersionNumber The attendee's version number.
AttendeeID Attendee unique identifier within SAP Concur.
AttendeeTypeCode The unique identifier for the attendee type.
AttendeeOwnerID The unique identifier for the person or system that owns the attendee.
CurrencyCode The 3-letter ISO 4217 currency code for attendee related amounts.

Report Details - Allocation

Element Description
AllocationID The unique alphanumeric identifier for the allocation. Maximum 13 characters.
Percentage The percentage of the expense that is included in this allocation. Maximum 11 characters.
AccountCode1 The primary accounting code assigned to the expense type associated with this allocation. Typically, expense types have only this primary account code.
AccountCode2 The secondary or alternative accounting code assigned to the expense type associated with this allocation. In rare cases some expense types include this accounting code to handle special cases. One example of these special cases is when using travel allowance, where one expense would use the primary account code for the allowed amount, and the alternative account code for the overage. Another example is personal use of a company car.
Refer to the Expense: Account Codes Setup Guide for more information on how Concur Expense determines which accounting codes to use.
Custom1 through Custom20 The custom fields associated with the allocation. These may not have data, depending on your configuration. Refer to the Custom Fields elements table for more information.
JournalEntriesList This parent element contains at least one JournalEntry child element. It contains multiple JournalEntry elements if the allocation has multiple journal entries. Refer to the JournalEntry elements table for more information.
VATDataList This parent element contains one VATData element for each VAT line item. This element will be empty if there are no VAT line items. Refer to the VATData elements table for more information.

JournalEntry

Element Description
JournalID Unique identifier for the journal entry.
PayerPaymentTypeName Payer payment type. Maximum 64 characters. One of these:
Company = Company
Employee = Employee
Payment Type for the Credit Card Payment Type
PayerPaymentTypeCode Payment code name for the payer. Maximum 80 characters.
PayeePaymentTypeName Payee payment type. Maximum 64 characters. One of these:
Company = Company
Employee = Employee
Payment Type for the Credit Card Payment Type
PayeePaymentCode Payment code name for the payee. Maximum 80 characters.
AccountCode The account code Concur Expense determines should apply to this journal entry. For journal entries associated to an allocation, Concur Expense uses the business logic described in the Expense: Account Codes Setup Guide to determine whether the primary or secondary account code should apply.  When there is no allocation associated to the journal entry, Concur Expense uses clearing account codes for Credit Card and Cash Advance for personal use of a company paid expense or a cash advance issued to an employee respectively. Maximum 48 characters.
NOTE: The developer should almost always use this accounting code when creating financial transactions in financial systems. In some situations a developer may need to use the accounting codes in the Allocation parent element.
DebitOrCredit Maximum 2 characters. Either:
DR = Debit
CR = Credit
Amount Value, as credit or debit, of the amount to be exchanged between the payer and payee for this expense account code (not an absolute value) Maximum 23 characters. EXAMPLES: Value of zero, credit, or debit, as the following:
0 (Zero) "0"
+ (Plus / Debit) "+50.00"
- (Minus / Credit) "-50.00"
JobRunKey Either the unique identifier for job run for the accounting extract that processed this journal, or a static value indicating the journal was processed by Manual Pay, Expense Pay, or some other system.

VATData

Element Description
TaxName Tax authority name. Maximum 50 characters.
TaxAuthorityLabel 5-digit code that appears on the expense entry pages. Maximum 5 characters.
TaxTransactionAmount Calculated tax amount for this expense in the spend currency. Maximum 23 characters.
TaxPostedAmount Calculated tax amount for this expense entry in the reimbursement currency. Maximum 23 characters.
Source Specifies how the tax data was derived. Maximum 4 characters. One of these:
CARD = Provided from company card
USER = Entered by employee
SYST = Calculated by system
PROC = Entered by processor
TaxReclaimTransactionAmount Calculated amount of tax eligible for reclaim in the spend currency. Maximum 23 characters.
TaxReclaimPostedAmount Calculated amount of tax eligible for reclaim in the reimbursement currency. Maximum 23 characters.

CardTransaction

Element Description
AccountNumber Credit card number used for this expense. This value is encrypted in the response. Maximum 255 characters.
CardDescription The name on the credit card used for this expense. Maximum 255 characters.
CardTypeCode Type of credit card.
TransactionReferenceNumber Reference number from the credit card vendor. Maximum 64 characters.
TransactionCCTType Transaction type supplied by card vendor. Maximum 3 characters. One of these:
ANF = Annual Fees
CAV = Cash Advance
CCF = Cash and Check Fees
CHG = Other Bank Charges and Fees
FNC = Finance Charges
LAF = Late Fees
NSF = Insufficient Funds Check Fees
PAY = Payment
RPE = Credit Card Transaction
TransactionID Calculated value assigned to this card entry during the import process. Maximum 32 characters.
TransactionAmount Amount of the charge in the spend currency. Maximum 23 characters.
TaxAmount Amount of tax on the transaction amount (if provided by card vendor). Maximum 23 characters.
TransactionAlphaCode Currency code for the spend currency. Maximum 3 characters. Format: ISO 4217 3 digit alpha code
PostedAmount Amount of the charge in the billing currency of the card. Maximum 23 characters.
PostedAlphaCode Currency code for the card billing currency. Maximum 3 characters. Format: ISO 4217 3 digit alpha code
TransactionDate Date the charge was made at the merchant. Maximum 10 characters.
PostedDate Date the charge was posted to the credit card account. Maximum 10 characters.
Description Description of the charge from the merchant. Maximum 42 characters.
MasterCardCode Merchant code sent from the credit card vendor. Maximum 5 characters.
TransactionMerchantName Name of the merchant. Maximum 50 characters.
MerchantCity Merchant city. Maximum 40 characters.
MerchantState Merchant State/Province. Maximum 32 characters.
MerchantCountryCode Merchant country location code. Format: 2 digit alpha code
MerchantReferenceNumber Merchant reference number passed from the merchant to the card. Maximum 15 characters.
ExchangeRateFromBillingToEmployeeCurrency Currency exchange rate used between the credit card billing currency and the employee's reimbursement currency. Maximum 23 characters.
BillingAmount Amount due to the company card from the employee or company (depending on who is responsible for the bill) for this detail row. Maximum 23 characters.
AccountNumberLastSegment The last 4 digits of the Card Account.

Custom Fields

Element Description
Type The custom field type. Will be one of the following: Amount, Boolean, ConnectedList, Date, Integer, List, Number, Text
Value The value in the custom field. Maximum 48 characters.
Code Custom list fields will include the list item code in this element.

ReportOwner

Element Description
EmployeeCustom21 The report owner's group ID. Maximum 48 characters.
EmployeeID Employee ID often also serves as the employee's Vendor ID for AP system integrations or Payroll ID for Payroll integrations. Maximum 48 characters.
EmployeeOrgUnit1 through EmployeeOrgUnit6 The report owner's organizational unit information. Maximum 48 characters for each field.
FirstName The report owner's first name. Maximum 32 characters.
LastName The report owner's last name. Maximum 32 characters.
MiddleInitial The report owner's middle initial. Maximum 1 character.
ReimbursementMethodCode The report owner's reimbursement method code, as defined in the employee's Profile.

EmployeeBankAccount

Element Description
BankNumber The bank identification number entered on the Bank Information page. Maximum 11 characters.
BankName The bank name entered on the Bank Information page. Maximum 48 characters.
BranchLocation The branch location entered on the Bank Information page. Maximum 30 characters.
AccountNumber The bank account number entered on the Bank Information page. Maximum 100 characters.
AccountName The name on the account entered on the Bank Information page.
PostalAddressLine1 The postal address line 1 entered on the Bank Information page. Maximum 48 characters.
PostalAddressLine2 The postal address line 2 entered on the Bank Information page. Maximum 48 characters.
PostalAddressCity The postal address city entered on the Bank Information page. Maximum 24 characters.
PostalAddressRegion The postal address region entered on the Bank Information page. Maximum 24 characters.
PostalAddressCode The postal address code entered on the Bank Information page. Maximum 20 characters.
PostalAddressCountry The postal address country entered on the Bank Information page. Maximum 2 characters. Format: The ISO 3166-1 alpha-2 country code. Example: United States is US.

Report Details - Examples

XML Example Request

GET https://www.concursolutions.com/api/expense/expensereport/v2.0/report/n6ujbuLd1Arwe45lT7As3ThJYJf2dAsrrEW HTTP/1.1
Authorization: OAuth {access token}
...

XML Example of Successful Response

HTTP/1.1 200 OK
Content-Type: application/xml

<?xml version="1.0" encoding="utf-8"?>
<ReportDetails xmlns="http://www.concursolutions.com/api/expense/expensereport/2012/07" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
    <UserLoginID>cm@example.com</UserLoginID>
    <EmployeeName>Miller, Chris</EmployeeName>
    <ReportID>425FE2ADB4954FCA90CD</ReportID>
    <ReportName>Client Meeting</ReportName>
    <Purpose>Sales meeting</Purpose>
    <ReportDate>2013-01-10T00:00:00</ReportDate>
    <CreationDate>2013-01-11T01:58:20</CreationDate>
    <SubmitDate>0001-01-01T00:00:00</SubmitDate>
    <PaidDate i:nil="true" />
    <CurrencyCode>USD</CurrencyCode>
    <ReportTotal>50.00000000</ReportTotal>
    <PersonalExpenses>0.00000000</PersonalExpenses>
    <AmountDueEmployee>50.00000000</AmountDueEmployee>
    <AmountDueCompanyCard>0.00000000</AmountDueCompanyCard>
    <TotalClaimedAmount>50.00000000</TotalClaimedAmount>
    <TotalApprovedAmount>50.00000000</TotalApprovedAmount>
    <ApprovalStatusCode>A_NOTF</ApprovalStatusCode>
    <ApprovalStatusName>Not Submitted</ApprovalStatusName>
    <PaymentStatusCode>P_NOTP</PaymentStatusCode>
    <PaymentStatusName>Not Paid</PaymentStatusName>
    <OrgUnit1>Sales</OrgUnit1>
    <OrgUnit2 />
    <OrgUnit3 />
    <OrgUnit4 />
    <OrgUnit5 />
    <OrgUnit6 />
    <Custom1 />
    <Custom2 />
    <Custom3 />
    <Custom4 />
    <Custom5 />
    <Custom6 />
    <Custom7 />
    <Custom8 />
    <Custom9 />
    <Custom10 />
    <Custom11 />
    <Custom12 />
    <Custom13 />
    <Custom14 />
    <Custom15 />
    <Custom16 />
    <Custom17 />
    <Custom18 />
    <Custom19 />
    <Custom20 />
    <LedgerName>Corporate</LedgerName>
    <PolicyID>ndrF8hjzl9FtFUdfaBwVvXP$sD1vDpRKNf</PolicyID>
    <EverSentBack>N</EverSentBack>
    <HasException>N</HasException>
    <WorkflowActionURL />
    <ExpenseEntriesList>
        <ExpenseEntry>
            <ReportEntryID>nE0avYnILN9mHdTErNSd2pH45udFoNQ$po</ReportEntryID>
            <ExpenseTypeID>BUSML</ExpenseTypeID>
            <ExpenseTypeName>Business Meal (attendees)</ExpenseTypeName>
            <SpendCategory>Entertainment</SpendCategory>
            <PaymentTypeCode>CASH</PaymentTypeCode>
            <PaymentTypeName>Cash</PaymentTypeName>
            <TransactionDate>2013-01-10T00:00:00</TransactionDate>
            <TransactionCurrencyName>US, Dollar</TransactionCurrencyName>
            <ExchangeRate>1.00000000000000</ExchangeRate>
            <TransactionAmount>50.00000000</TransactionAmount>
            <PostedAmount>50.00000000</PostedAmount>
            <ApprovedAmount />
            <BusinessPurpose />
            <VendorDescription />
            <LocationName>Washington</LocationName>
            <LocationSubdivision>US-DC</LocationSubdivision>
            <LocationCountry>US</LocationCountry>
            <OrgUnit1>Sales</OrgUnit1>
            <OrgUnit2 />
            <OrgUnit3 />
            <OrgUnit4 />
            <OrgUnit5 />
            <OrgUnit6 />
            <Custom1 />
            <Custom2 />
            <Custom3 />
            <Custom4 />
            <Custom5 />
            <Custom6 />
            <Custom7 />
            <Custom8 />
            <Custom9 />
            <Custom10 />
            <Custom11 />
            <Custom12 />
            <Custom13 />
            <Custom14 />
            <Custom15 />
            <Custom16 />
            <Custom17 />
            <Custom18 />
            <Custom19 />
            <Custom20 />
            <Custom21 />
            <Custom22 />
            <Custom23 />
            <Custom24 />
            <Custom25 />
            <Custom26 />
            <Custom27 />
            <Custom28 />
            <Custom29 />
            <Custom30 />
            <Custom31 />
            <Custom32 />
            <Custom33 />
            <Custom34 />
            <Custom35 />
            <Custom36 />
            <Custom37 />
            <Custom38 />
            <Custom39 />
            <Custom40 />
            <FormID>nAaT8$puKKOhs7h2wespCW7vyyxJAJcyb5</FormID>
            <EntryImageID />
            <HasVat>N</HasVat>
            <HasComments>N</HasComments>
            <CommentCount>0</CommentCount>
            <IsItemized>Y</IsItemized>
            <HasExceptions>N</HasExceptions>
            <IsPersonal>N</IsPersonal>
            <HasAttendees>Y</HasAttendees>
            <HasAllocation>N</HasAllocation>
            <IsCreditCardCharge>N</IsCreditCardCharge>
            <IsPersonalCardCharge>N</IsPersonalCardCharge>
            <ReceiptRequired>N</ReceiptRequired>
            <ImageRequired>N</ImageRequired>
            <E-ReceiptID />
            <LastModified>2013-01-11T01:59:52</LastModified>
            <ItemizationsList>
                <Itemization>
                    <ItemType>Regular</ItemType>
                    <ItemizationID>nE0avYnILN9mHdTErNSd2pH45udFoNQ$po</ItemizationID>
                    <ExpenseTypeID>BUSML</ExpenseTypeID>
                    <ExpenseTypeName>Business Meal (attendees)</ExpenseTypeName>
                    <TransactionDate>2013-01-10T00:00:00</TransactionDate>
                    <TransactionAmount>50.00000000</TransactionAmount>
                    <PostedAmount>50.00000000</PostedAmount>
                    <ApprovedAmount />
                    <BusinessPurpose />
                    <OrgUnit1>Sales</OrgUnit1>
                    <OrgUnit2 />
                    <OrgUnit3 />
                    <OrgUnit4 />
                    <OrgUnit5 />
                    <OrgUnit6 />
                    <Custom1 />
                    <Custom2 />
                    <Custom3 />
                    <Custom4 />
                    <Custom5 />
                    <Custom6 />
                    <Custom7 />
                    <Custom8 />
                    <Custom9 />
                    <Custom10 />
                    <Custom11 />
                    <Custom12 />
                    <Custom13 />
                    <Custom14 />
                    <Custom15 />
                    <Custom16 />
                    <Custom17 />
                    <Custom18 />
                    <Custom19 />
                    <Custom20 />
                    <Custom21 />
                    <Custom22 />
                    <Custom23 />
                    <Custom24 />
                    <Custom25 />
                    <Custom26 />
                    <Custom27 />
                    <Custom28 />
                    <Custom29 />
                    <Custom30 />
                    <Custom31 />
                    <Custom32 />
                    <Custom33 />
                    <Custom34 />
                    <Custom35 />
                    <Custom36 />
                    <Custom37 />
                    <Custom38 />
                    <Custom39 />
                    <Custom40 />
                    <HasComments>N</HasComments>
                    <CommentCount>0</CommentCount>
                    <IsPersonal>N</IsPersonal>
                    <LastModified>2013-01-11T01:59:52</LastModified>
                    <AllocationsList />
                    <AttendeesList>
                        <Attendee>
                            <AttendeeType>BUSGUEST</AttendeeType>
                            <FirstName>Pat</FirstName>
                            <LastName>Davis</LastName>
                            <Company />
                            <Title />
                            <ExternalID />
                            <Custom1 />
                            <Custom2 />
                            <Custom3 />
                            <Custom4 />
                            <Custom5 />
                            <Custom6 />
                            <Custom7 />
                            <Custom8 />
                            <Custom9 />
                            <Custom10 />
                            <Custom11 />
                            <Custom12 />
                            <Custom13 />
                            <Custom14 />
                            <Custom15 />
                            <Custom16 />
                            <Custom17 />
                            <Custom18 />
                            <Custom19 />
                            <Custom20 />
                            <HasExceptionsPrevYear>N</HasExceptionsPrevYear>
                            <HasExceptionsYTD>N</HasExceptionsYTD>
                            <IsDeleted>N</IsDeleted>
                            <OwnerEmpName>Miller, Chris</OwnerEmpName>
                            <TotalAmountPrevYear>0.00000000</TotalAmountPrevYear>
                            <TotalAmountYTD>0.00000000</TotalAmountYTD>
                            <VersionNumber>1</VersionNumber>
                            <AttendeeID>nFaAj038Hw$plfUD8be0I45wTx8$sMlTd$pP</AttendeeID>
                            <AttendeeTypeCode>BUSGUEST</AttendeeTypeCode>
                            <AttendeeOwnerID>cm@example.com</AttendeeOwnerID>
                            <CurrencyCode>USD</CurrencyCode>
                        </Attendee>
                    </AttendeesList>
                </Itemization>
                <Itemization>
                    <ItemType>Child</ItemType>
                    <ItemizationID>nE0avYnILN9g$s6lCFX0jFBWmHAiTYYf9C</ItemizationID>
                    <ExpenseTypeID>BRKFT</ExpenseTypeID>
                    <ExpenseTypeName>Breakfast</ExpenseTypeName>
                    <TransactionDate>2013-01-10T00:00:00</TransactionDate>
                    <TransactionAmount>50.00000000</TransactionAmount>
                    <PostedAmount>50.00000000</PostedAmount>
                    <ApprovedAmount>50.00000000</ApprovedAmount>
                    <BusinessPurpose />
                    <OrgUnit1>Sales</OrgUnit1>
                    <OrgUnit2 />
                    <OrgUnit3 />
                    <OrgUnit4 />
                    <OrgUnit5 />
                    <OrgUnit6 />
                    <Custom1 />
                    <Custom2 />
                    <Custom3 />
                    <Custom4 />
                    <Custom5 />
                    <Custom6 />
                    <Custom7 />
                    <Custom8 />
                    <Custom9 />
                    <Custom10 />
                    <Custom11 />
                    <Custom12 />
                    <Custom13 />
                    <Custom14 />
                    <Custom15 />
                    <Custom16 />
                    <Custom17 />
                    <Custom18 />
                    <Custom19 />
                    <Custom20 />
                    <Custom21 />
                    <Custom22 />
                    <Custom23 />
                    <Custom24 />
                    <Custom25 />
                    <Custom26 />
                    <Custom27 />
                    <Custom28 />
                    <Custom29 />
                    <Custom30 />
                    <Custom31 />
                    <Custom32 />
                    <Custom33 />
                    <Custom34 />
                    <Custom35 />
                    <Custom36 />
                    <Custom37 />
                    <Custom38 />
                    <Custom39 />
                    <Custom40 />
                    <HasComments>N</HasComments>
                    <CommentCount>0</CommentCount>
                    <IsPersonal>N</IsPersonal>
                    <LastModified>2013-01-11T01:59:52</LastModified>
                    <AllocationsList>
                        <Allocation>
                            <AllocationID>ngYn5SB4OUXgRV6P8VgsQQr88SaKYvbqz</AllocationID>
                            <Percentage>100.00000000%</Percentage>
                            <AccountCode1>AC_BRKFT1</AccountCode1>
                            <AccountCode2>AC_BRKFT2</AccountCode2>
                            <Custom1 />
                            <Custom2 />
                            <Custom3 />
                            <Custom4 />
                            <Custom5 />
                            <Custom6 />
                            <Custom7 />
                            <Custom8 />
                            <Custom9 />
                            <Custom10 />
                            <Custom11 />
                            <Custom12 />
                            <Custom13 />
                            <Custom14 />
                            <Custom15 />
                            <Custom16 />
                            <Custom17 />
                            <Custom18 />
                            <Custom19 />
                            <Custom20 />
                            <VATDataList />
                        </Allocation>
                    </AllocationsList>
                    <AttendeesList />
                </Itemization>
            </ItemizationsList>
            <UserLoginID>cm@example.com</UserLoginID>
        </ExpenseEntry>
    </ExpenseEntriesList>
    <Country>US</Country>
    <CountrySubdivision></CountrySubdivision>
    <ProcessingPaymentDate></ProcessingPaymentDate>
    <ReceiptsReceived>Y</ReceiptsReceived>
    <ReportOwner>
        <EmployeeID>cm@example.com</EmployeeID>
        <LastName>Chris</LastName>
        <FirstName>Miller</FirstName>
        <MiddleInitial></MiddleInitial>
        <EmployeeCustom21></EmployeeCustom21>
        <EmployeeOrgUnit1></EmployeeOrgUnit1>
        <EmployeeOrgUnit2></EmployeeOrgUnit2>
        <EmployeeOrgUnit3></EmployeeOrgUnit3>
        <EmployeeOrgUnit4></EmployeeOrgUnit4>
        <EmployeeOrgUnit5></EmployeeOrgUnit5>
        <EmployeeOrgUnit6></EmployeeOrgUnit6>
        <ReimbursementMethodCode>CNQRPAY</ReimbursementMethodCode>
    </ReportOwner>
</ReportDetails>

Payment Batches

The Payment Batch File web service provides an automated solution to clients who would like to manage their payment batches and collect their batch files.

Process Flow

Process Flow for Payment Batch

Product and Edition

Concur Expense Standard Edition

NOTE: For Concur Expense Professional Edition, use Extracts v1 API

Retrieve the List of Payment Batches

Retrieves the list of payment batches with an optional requested status.

GET /api/expense/paymentbatch/v1.1/batchlist/

Parameters

Name Type Format Description
batchlist string - Required. The batchlist keyword.
Status Boolean - The status of the batches. Can be either OPEN or CLOSED.

Retrieve Payment Batches Response Schema

Name Type Format Description
BatchName string - The batch name, as it appears in Payment Manager.
BatchID string - The unique identifier for the batch.
BatchTotal Decimal - The batch total amount.
Currency string - The 3-letter ISO 4217 currency code for the batch.
Count string - The number of payment demands in the batch.
Type string - The payee of the batch. Either Employee or Card Program.
PaymentMethod string - The reimbursement method for the batch. Either Expense Pay by SAP Concur, Company Check (via Accounts Payable), ADP (via EPIP file), or Other Reimbursement Methods.
Batch-URL string - The URL to use as a basis for other actions, such as closing the batch.

Close a Payment Batch Asynchronously

Version 1.2

This asynchronous request schedules closing of the specified batch, preventing any new expenses from entering it. After the batch closes, you can use Close Payment Batch v1.1 to get the File-Url to download the file containing the expense transaction information.

Note: You can check batch status using the Retrieve the List of Payment Batches method.

POST /api/expense/paymentbatch/v1.2/batch/{BatchID}/close

Parameters

Name Type Format Description
BatchID string - Required. The unique identifier for the batch.
close string - Required. The close keyword.

Close Payment Batch Asynchronously Response Schema

Name Type Format Description
Status string - The status of the request to close the batch.
JobQueueKey string - The unique identifier for the batch job.

Close a Payment Batch Synchronously

Version 1.1

This request synchronously closes the batch preventing any new expenses from entering it. After the batch closes, SAP Concur creates the batch file containing the expense transaction information. If a batch ID for an already closed batch is sent, SAP Concur regenerates the batch file for the specified batch.

This synchronous call has a time limit that can be superseded by the time it takes to close the batch. It is recommended that you use Close a Payment Batch Asynchronously (v1.2) to close batches, then use this request after the batch is closed to obtain the File-Url needed to download the file with the expense transaction information.

Note: You can check batch status using the Retrieve the List of Payment Batches method.

POST /api/expense/paymentbatch/v1.1/batch/{BatchID}/close

Parameters

Name Type Format Description
BatchID string - Required. The unique identifier for the batch.
close string - Required. The close keyword.

Close Payment Batch Synchronously Response Schema

Name Type Format Description
BatchStatus string - The current status of the specified batch.
File-Url string - A URL for retrieving the extract file or files produced when the batch closes, with encrypted ID.
Status string - The status of the request to close the batch.

Retrieve a Payment Batch File

Requests the expense transaction data for the specified payment batch.

GET /api/expense/paymentbatch/v1.1/batch/{JobRunKey}/file

Parameters

Name Type Format Description
JobRunKey string - Required. The File-Url element returned by the Close Batches 1.1 API response contains the encrypted JobRunKey. In practice, you can use the File-Url whole value to download the file.

Retrieve Payment Batch File Response Schema

This request will return the expense transaction data in text/csv format if there was a single file produced or as a zip archive if the batch is configured to produce more than one file. An example of a client who will receive multiple files is a client using QuickBooks, who receives one file formatted for import into QuickBooks (.IIF extension), and one file for the general ledger (.CSV extension), inside a .ZIP file.

Error Messages

Error Number Description
500 The batch you attempted to close does not contain any reports. If you recently approved reports for payment, wait 30 minutes and try again.

Enterprise Resource Planning Integration

Before you begin, you need to close the Payment Manager batch in order for you to retrieve the files using this API. Ask your client not to close the batch manually through the user interface.

  1. Obtain a list of your client’s batches by using Get list of batches
  2. Close the desired batch by using Close a payment batch
  3. Retrieve the file you want by using Retrieve a payment batch file

Quick Expense v4

The Quick Expense API can be used to create an expense with basic information such as date, amount, and expense type, with or without a receipt image. This expense can be added to an expense report within Concur Expense, allowing the user to provide additional details such as attendees, itemizations etc.

Limitations: This API is only available to partners who have been granted access by SAP Concur. Access to this documentation does not provide access to the API. This API is not available in Implementation environments.

Quick Expense - Products and Editions

Quick Expense - Scope Usage

Required Scopes:

Name Description Endpoint
quickexpense.writeonly Write quick expense. POST
user.read Get User Information, necessary for userID. POST
receipts.writeonly Required if e-Bunsho is enabled Write quick expense. POST

Optional Scope:

Name Description Endpoint
CONFIG Get Expense Configuration information, necessary for expenseTypeId. POST

Quick Expense - Dependencies

SAP Concur clients must purchase Concur Expense in order to use this API. This API requires the User v3.1 API which is currently only available to approved early access partners. Please contact your SAP Concur representative for more information.

The partner may use the following SAP Concur APIs to get optional information: * Expense Group Configurations v3.0, to retrieve the expenseTypeId * Locations v3.0, to retrieve the location id

Japan Market: If the partner is using this API to provide the e-Bunsho digital timestamp for the receipt, the partner should confirm that the client has e-Bunsho activated in SAP Concur.

Quick Expense - Access Token Usage

This API supports both company level and user level access tokens.

Create a Quick Expense

Creates a quick expense without an image.

Scopes

quickexpense.writeonly - Refer to Scope Usage for full details.

Request

URI

Template

https://{datacenterURI}/quickexpense/v4/users/{userID}/context/{contextType}/quickexpenses

Parameters

Name Type Format Description
userID string - Required The unique identifier of the SAP Concur user. Use User Profile v1.0 to retrieve the userID.
contextType string - Required The access level of the SAP Concur user, which determines the form fields they can view/modify. Supported value: TRAVELER.

Headers

Payload

Response

Status Codes

Headers

Payload

Example

Request

curl -X POST \
  https://us.api.concursolutions.com/quickexpense/v4/users/184dd31a-f48a-4103-879f-c8d45456c7cd/context/TRAVELER/quickexpenses \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access_token}' \
  -H 'Content-Type: application/json' \
  -H 'concur-correlationid: quick-expense-test' \
  -d '{
  "comment": "Offsite team lunch.",
  "expenseTypeId": "BUSML",
  "entryDetails": "test-entry",
  "location": {
    "city": "Bellevue",
    "countryCode": "US",
    "countrySubDivisionCode": "US-WA",
    "id": "",
    "name": ""
  },
  "paymentTypeId": "CASHX",
  "transactionAmount": {
    "currencyCode": "USD",
    "value": 88.05
  },
  "transactionDate": "2019-02-04"
}'

Response

201 Created

{
    "quickExpenseIdUri": "https://seapr1qes.concurasp.com/quickexpense/v4/users/184dd31a-f48a-4103-879f-c8d45456c7cd/context/TRAVELER/quickexpenses/E018795D2B09094FBF223E209E921B88"
}

Create a Quick Expense with an Image

Creates a quick expense with an image.

Scopes

quickexpense.writeonly - Refer to Scope Usage for full details. receipts.writeonly - Refer to Scope Usage for full details.

Request

URI

Template

https://{datacenterURI}/quickexpense/v4/users/{userID}/context/{contextType}/quickexpenses/image
Parameters
Name Type Format Description
userID string - Required The unique identifier of the SAP Concur user. Use User Profile v1.0 to retrieve the userID.
contextType string - Required The access level of the SAP Concur user, which determines the form fields they can view/modify. Supported values: TRAVELER.
fileContent file - Required The quick expense image. Maximum size 5 MBs. Supported image types are: PNG, PDF, TIFF, JPEG

Headers

Payload

Response

Status Codes

Headers

Payload

Example

Request

curl -X POST \
  https://us.api.concursolutions.com/quickexpense/v4/users/184dd31a-f48a-4103-879f-c8d45456c7cd/context/TRAVELER/quickexpenses/image \
  -H 'Authorization: Bearer {access_token}' \
  -H 'Content-Type: multipart/form-data' \
  -H 'concur-correlationid: quick-expense-with-image' \
  -H 'content-type: multipart/form-data' \
  -F fileContent=@/Users/i845500/Pictures/Snip20180410_1.png \
  -F 'quickExpenseRequest={
  "comment": "Offsite team lunch.",
  "expenseTypeId": "BUSML",
  "entryDetails": "test-entry",
  "location": {
    "city": "Bellevue",
    "countryCode": "US",
    "countrySubDivisionCode": "US-WA",
    "id": "",
    "name": ""
  },
  "paymentTypeId": "CASHX",
  "transactionAmount": {
    "currencyCode": "USD",
    "value": 88.05
  },
  "transactionDate": "2019-02-04"
}'

Response

201 Created

{
    "quickExpenseIdUri": "https://seapr1qes.concurasp.com/quickexpense/v4/users/184dd31a-f48a-4103-879f-c8d45456c7cd/context/TRAVELER/quickexpenses/A0D1CE97B4692B4F8E29BEA53B250E36"
}

Quick Expense - Schema

Quick Expense Request

Name Type Format Description
comment string - This is a comment attached to the quick expense.
entryDetails string - The quick expense entry details.
expenseTypeId string - Required This is the expense type id of quick expense. Use Expense Group Configurations v3.0 to retrieve the supported expense types. Supported values for a null value are: UNDEF, NULL. NULL can only be used on a POST operation and will be converted to UNDEF.
location - Location The location where the quick expense occurred.
paymentTypeId string - This is the payment type id of quick expense. Supported values: CASHX, CPAID, PENDC.
transactionAmount - Amount Required The amount of the quick expense.
transactionDate string YYYY-MM-DD Required This is the transaction date of the quick expense.
vendor string - The name of the vendor.

Location

Name Type Format Description
city string - The location city.
countryCode string - The location country ISO 3166-1 code.
countrySubDivisionCode string - The location country sub division ISO 3166-2 code.
id string - The unique identifier of the location. Use Locations v3.0 to retrieve the location id.
name string - The location name.

Amount

Name Type Format Description
currencyCode string - Required The 3-letter ISO 4217 currency code.
value number - Required The amount value.

Quick Expense Response

Name Type Format Description
quickExpenseIdUri string - The quick expense created resource url.

Quick Expense - Error

Name Type Format Description
errorId string - The unique identifier of the error.
errorMessage string - Required Message associated with the error.
httpStatus string - The HTTP status associated with the error.
path string - The path to the resource.
timestamp string - The timestamp for the error.
validationErrors array validationErrors An array of validation errors.

Validation Errors

Name Type Format Description
message string - The validation error message.
source string - The source of the validation error.

Financial Integration Service v4

Getting Started - Financial Integration Service v4

The Financial Integration API allows an external system to interact with financial documents generated from SAP Concur, for financial posting into an ERP.

This API provides an automated solution to request available data objects such as approved expense reports, cash advances, and invoices to import to the client internal system, with an opportunity to send posting confirmation back into SAP Concur before the object is locked down and cannot be altered in SAP Concur.

Below are some benefits for using the Financial Integration service:

Contents

Financial Integration - Products and Editions

Financial Integration - Scope Usage

Name Description Endpoint
FISVC Read financial transactions and write financial transaction acknowledgements and confirmations. GET, POST

Financial Integration - Access Token Usage

This API only supports company-level access tokens.

Get Financial Transactions

The request returns a list of financial documents that are ready to be processed. The request can include parameters to limit the results.

Scopes

FISVC - Refer to Scope Usage for full details.

Request

URI

Template
https://{datacenterURI}/financialintegration/fi/v4/companies/transactiontypes/{docType}/transactions
Parameters
Name Type Format Description
docType string path Required The financial document type to return. Only one type of transaction can be retrieved at a time. Supported values are: expense, invoice, cashadvance, payroll, obligation.
page int32 query Starting page number.
limit int32 query Number of records to return per page (default 25).
docId string query The transaction unique identifier, it could be expense report ID, payment request ID or cash advance ID. If specified, a single document that matches docId is returned.
ignoreDocumentStatus string query Ignores the financial documents status. Supported values are: yes or no. If yes, a document is returned regardless of status. If no, only documents that have not been acknowledged/confirmed are returned.
systemId string query The external system ID that processed the document. Maximum 50 characters.

Headers

Payload

None.

Response

Status Codes

Headers

Payload

Financial Documents

Example

Request

GET https://us.api.concursolutions.com/financialintegration/fi/v4/companies/transactiontypes/expense/transactions?limit=3
Authorization: Bearer {token}

Response

200 OK
Content-Type: application/json
Date: {date-requested}
Content-Length: 491
{
  "links" : [ {
    "rel" : "first",
    "href" : "https://fiserviceurlhere/fi/v4/companies/transactiontypes/expense/transactions?limit=3&page=0&size=3",
    "hreflang" : null,
    "media" : null,
    "title" : null,
    "type" : null,
    "deprecation" : null
  }, {
    "rel" : "self",
    "href" : "https://fiserviceurlhere/fi/v4/companies/transactiontypes/expense/transactions?limit=3&page=0&size=3",
    "hreflang" : null,
    "media" : null,
    "title" : null,
    "type" : null,
    "deprecation" : null
  }, {
    "rel" : "next",
    "href" : "https://fiserviceurlhere/fi/v4/companies/transactiontypes/expense/transactions?limit=3&page=1&size=3",
    "hreflang" : null,
    "media" : null,
    "title" : null,
    "type" : null,
    "deprecation" : null
  }, {
    "rel" : "last",
    "href" : "https://fiserviceurlhere/fi/v4/companies/transactiontypes/expense/transactions?limit=3&page=2&size=3",
    "hreflang" : null,
    "media" : null,
    "title" : null,
    "type" : null,
    "deprecation" : null
  } ],
  "content" : [ {
    "id" : "e7f810cabc8348cdb051dd9431c8cfbb",
    "docType" : "expense",
    "companyId" : "COMPANY_ID_HERE",
    "entityId" : "ENTITY_ID_HERE",
    "companyUuid" : "COMPANY_UUID_HERE",
    "erpSystemId" : "",
    "document" : "{THE_FINANCIAL_DOCUMENT}",
    "docStatus" : "READY",
    "links" : [ ]
  }, {
    "id" : "e1500222f16748718fdd2d493ee4c9dd",
    "docType" : "expense",
    "companyId" : "COMPANY_ID_HERE",
    "entityId" : "ENTITY_ID_HERE",
    "companyUuid" : "COMPANY_UUID_HERE",
    "erpSystemId" : null,
    "document" : "{THE_FINANCIAL_DOCUMENT}",
    "docStatus" : "READY",
    "links" : [ ]
  }, {
    "id" : "e2135678f16748718fdd2d493ee4c9dd",
    "docType" : "expense",
    "companyId" : "COMPANY_ID_HERE",
    "entityId" : "ENTITY_ID_HERE",
    "companyUuid" : "COMPANY_UUID_HERE",
    "erpSystemId" : null,
    "document" : "{THE_FINANCIAL_DOCUMENT}",
    "docStatus" : "READY",
    "links" : [ ]
  }
   ],
  "page" : {
    "size" : 3,
    "totalElements" : 8,
    "totalPages" : 3,
    "number" : 0
  }
}

Post Financial Transaction Acknowledgements

Allows an external system to acknowledge that it has successfully retrieved one or more financial transactions from SAP Concur and will begin processing those transactions. The transactions in the POST request are then taken out of the ready queue.

Scopes

FISVC - Refer to Scope Usage for full details.

Request

URI

Template
https://{datacenterURI}/financialintegration/fi/v4/companies/transactiontypes/{docType}/transactions/acknowledgements
Parameters
Name Type Format Description
docType string path Required The financial document type. Only one type of transaction can be acknowledged at a time. Supported values are: expense, invoice, cashadvance, payroll, obligation.

Headers

Payload

AcknowledgeRequest

Response

Status Codes

Headers

Payload

AcknowledgeResponse

Example

Request

POST https://us.api.concursolutions.com/financialintegration/fi/v4/companies/transactiontypes/expense/transactions/acknowledgements
Authorization: Bearer {token}
Content-Type: application/json
{
  "ids": [ "5ab9224e02e840148e7cd7d9e8e72968", "2ac9224e02e840148e7cd7d9e8e12345" ]
}

Response

This response shows both success and failure service code examples.

200 OK
Content-Type: application/json
Date: {date-requested}
Content-Length: 372
[
  {
    "code": 0,
    "docId": "5ab9224e02e840148e7cd7d9e8e72968",
    "systemId": null,
    "acknowledgeResult": "SUCCESS",
    "errorMessage": ""
  },
  {
    "code": 101,
    "docId": "2ac9224e02e840148e7cd7d9e8e12345",
    "systemId": null,
    "acknowledgeResult": "FAILURE",
    "errorMessage": "This document was previously acknowledged by SystemId: null."
  }
]

Post Financial Transactions Confirmations

Allows financial posting results to be sent to SAP Concur.

Scopes

FISVC - Refer to Scope Usage for full details.

Request

URI

Template
https://{datacenterURI}/financialintegration/fi/v4/companies/transactiontypes/{docType}/transactions/postingconfirmations
Parameters
Name Type Format Description
docType string path Required The financial document type to return. expense, invoice, cashadvance, payroll, obligation. Only one type of transaction can be retrieved at a time.
confirmationRequest - body Required The JSON request to be posted.

Headers

Payload

Confirmation Request

Response

Status Codes

Headers

Payload

Posting Confirmation Response

Example

Request

POST https://us.api.concursolutions.com/financialintegration/fi/v4/companies/transactiontypes/expense/transactions/postingconfirmations
Authorization: Bearer {token}
Content-Type: application/json
{
  "systemId":"",
  "postingConfirmations":
  [
    {
      "docId":"0c06ab044834454d91f83cbd7b6431d2",
      "overallPostingStatusCode":"error",
      "postingDocs":[],
      "systemMessages":
      [
        {
          "concurTransactionLineItemId":"",
          "messageId":"010-CTE-POSTING",
          "messageLanguage":"EN",
          "messageLongText":"",
          "messageShortText":"Expense Report {ReportKey} of system CONCUR could not be posted."
        },
        {
          "concurTransactionLineItemId":"",
          "messageId":"003-CC",
          "messageLanguage":"EN",
          "messageLongText":"",
          "messageShortText":"Profit centre /company code assignment is not correct. Check the entry."
        }
      ]
    },
    {
      "docId":"3331dbeb8e2240ffad7ab5b69492722a",
      "overallPostingStatusCode":"success",
      "postingDocs":
      [
        {
          "companyId":"0100",
          "documentNumber":"0123456",
          "fiscalYear":"2018",
          "paymentRelevantLineItems":[],
          "postingDate":"2018-03-02"
        },
        {
          "companyId":"0800",
          "documentNumber":"0123478",
          "fiscalYear":"2018",
          "paymentRelevantLineItems":[],
          "postingDate":"2018-03-02"
        }
      ],
      "systemMessages":[]
    }
  ]
}

Response

This response shows both success and failure service code examples.

200 OK
Content-Type: application/json
Date: {date-requested}
Content-Length: 405
[
  {
    "code": 0,
    "docId": "0c06ab044834454d91f83cbd7b6431d2",
    "systemId": null,
    "postingConfirmationResult": "SUCCESS",
    "errorMessage": "",
    "detailMessage": ""
  },
  {
    "code": 116,
    "docId": "3331dbeb8e2240ffad7ab5b69492722a",
    "systemId": "",
    "postingConfirmationResult": "FAILURE",
    "errorMessage": "This document does not exist.",
    "detailMessage": ""
  }
]

Post Financial Payment Confirmations

Allows financial payment results to be sent to SAP Concur.

Scopes

FISVC - Refer to Scope Usage for full details.

Request

URI

Template
https://{datacenterURI}/financialintegration/fi/v4/companies/transactiontypes/{docType}/transactions/paymentconfirmations
Parameters
Name Type Format Description
docType string path Required The financial document type to return. expense, invoice, cashadvance, payroll, obligation. Only one type of transaction can be retrieved at a time.
confirmationRequest body Required The JSON request to be posted.

Headers

Payload

Payment Confirmation Request

Response

Status Codes

Headers

Payload

Payment Confirmation Response

Example

Request

POST https://us.api.concursolutions.com/financialintegration/fi/v4/companies/transactiontypes/expense/transactions/paymentconfirmations
Authorization: Bearer {token}
Content-Type: application/json
{
  "systemId":"",
  "processingConfirmation":
  [
    {
      "docId":"0c06ab044834454d91f83cbd7b6431d2",
      "processingStatusCode":"CP",
      "clearingDetails":[
        {
          "clearingDate":"2019-02-06T12:00:00.27Z","clearingAmount":220.00,
          "clearingCurrency":"USD","receiver":{"receiverId":"22344",
          "receiverName":"Charles","receiverType":"EMPLOYEE"},
          "clearingReference":{"companyCode":"US01","financialDocumentId":"667799",
          "fiscalYear":"2019","paymentRef":"US01/667799/2019/2","paymentMethod":"E"}
        }
      ]
    },
    {
      "docId":"454d91f83cbd7b6431d20c06ab044834",
      "processingStatusCode":"PP",
      "clearingDetails":[
        {
          "clearingDate":"2019-02-06T12:00:00.27Z","clearingAmount":40.00,
          "clearingCurrency":"USD","receiver":{"receiverId":"57",
          "receiverName":"John","receiverType":"EMPLOYEE"},
          "clearingReference":{"companyCode":"US01","financialDocumentId":"996675",
          "fiscalYear":"2019","paymentRef":"US01/996675/2019/2","paymentMethod":"E"}
        }
      ]
    },
    {
      "docId":"1d20c06ab0445d7b64348344d91f83cb",
      "processingStatusCode":"PP",
      "clearingDetails":[
        {
          "clearingDate":"2019-02-06T12:00:00.27Z","clearingAmount":23.00,
          "clearingCurrency":"USD","receiver":{"receiverId":"57",
          "receiverName":"Alice","receiverType":"EMPLOYEE"},
          "clearingReference":{"companyCode":"US01","financialDocumentId":"95432",
          "fiscalYear":"2019","paymentRef":"US01/95432/2019/2","paymentMethod":"E"}
        }
      ]
    },
    {
      "docId":"d2454d91fcb44834830c06ab0d7b6431",
      "processingStatusCode":"RE",
      "additionalMessage":"This report was sent to wrong system",
      "clearingDetails":[
        {
          "clearingDate":"2019-02-06T12:00:00.27Z","clearingAmount":10.00,
          "clearingCurrency":"USD","receiver":{"receiverId":"57",
          "receiverName":"Peter","receiverType":"EMPLOYEE"},
          "clearingReference":{"companyCode":"US01","financialDocumentId":"5498",
          "fiscalYear":"2019","paymentRef":"US01/5498/2019/2","paymentMethod":"E"}
        }
      ]
    },
    {
      "docId":"b6431d2454dcbd791f44834830c06ab0",
      "processingStatusCode":"OB",
      "additionalMessage":"Not required anymore",
      "clearingDetails":[
        {
          "clearingDate":"2019-02-06T12:00:00.27Z","clearingAmount":54.00,
          "clearingCurrency":"USD","receiver":{"receiverId":"57",
          "receiverName":"Kevin","receiverType":"EMPLOYEE"},
          "clearingReference":{"companyCode":"US01","financialDocumentId":"32478",
          "fiscalYear":"2019","paymentRef":"US01/32478/2019/2","paymentMethod":"E"}
        }
      ]
    }
  ]
}

Response

This response shows both success and failure service code examples.

200 OK
Content-Type: application/json
Date: {date-requested}
Content-Length: 405
[
  {
  "code" : 0,
  "docId" : "0c06ab044834454d91f83cbd7b6431d2",
  "systemId" : "",
  "paymentConfirmationResult" : "SUCCESS",
  "errorMessage" : null,
  "paymentRef" : "US01/667799/2019/2",
  "detailMessage" : ""
  },
  {
  "code" : 116,
  "docId" : "454d91f83cbd7b6431d20c06ab044834",
  "systemId" : "",
  "paymentConfirmationResult" : "FAILURE",
  "errorMessage" : "This document does not exist.",
  "paymentRef" : "US01/996675/2019/2",
  "detailMessage" : ""
  },
  {
  "code" : 298,
  "docId" : "1d20c06ab0445d7b64348344d91f83cb",
  "systemId" : "",
  "paymentConfirmationResult" : "NOOP",
  "errorMessage" : "Payment confirmation already exist US01/95432/2019/2.",
  "paymentRef" : "US01/95432/2019/2",
  "detailMessage" : ""
  }
  {
  "code" : 0,
  "docId" : "d2454d91fcb44834830c06ab0d7b6431",
  "systemId" : "",
  "paymentConfirmationResult" : "SUCCESS",
  "errorMessage" : null,
  "paymentRef" : "US01/5498/2019/2",
  "detailMessage" : ""
  },
  {
  "code" : 0,
  "docId" : "b6431d2454dcbd791f44834830c06ab0",
  "systemId" : "",
  "paymentConfirmationResult" : "SUCCESS",
  "errorMessage" : null,
  "paymentRef" : "US01/32478/2019/2",
  "detailMessage" : ""
  }
]

Service Codes

The Financial Integration Service will return service codes based on the success and failure of individual records for acknowledging and posting confirmation of documents.

Code Description Category
0 Successfully processed Any
99 System ID in request does not match system ID in FI database. Any
101 This document was previously acknowledged. Acknowledge
102 This document has been recalled. Acknowledge
103 This document is not ready. Acknowledge
104 This document does not exist in the FI database. Acknowledge
105 This document is not of type (expense, invoice, cashadvance). Acknowledge
111 This document has not been acknowledged. Posting
112 This document has been recalled. Posting
113 Confirmation has been posted for this document. Posting
114 Document is not in a known state. Posting
115 This document is not of type (expense, invoice, cashadvance). Posting
116 This document does not exist in the FI database. Posting
198 Invalid request - this same request will not work if tried again. Posting
199 Unknown error, please try again later. Any

Financial Integration - Schema

Financial Documents

Name Type Format Description
content Array FIDocument The result collection.
page string PageMetadata Pagination details.
links Array Link Pagination links.

FIDocument

Name Type Format Description
id string - The unique identifier for the document.
docType string - Transaction type. Supported values are: expense, invoice, cashadvance, payroll, obligation.
companyId string - Unique identifier for the company in SAP Concur. Maximum 32 chars.
entityId string - Unique identifier for the entity in SAP Concur. Maximum 32 chars.
companyUuid string UUID UUID for the company in SAP Concur. Maximum 36 chars.
erpSystemId string - The external System ID that processed the document. Maximum 50 chars.
document Array - The JSON financial document. Review the FI sample documents below.
docStatus string - The financial document status. Supported values are: READY, ACKNOWLEDGED, POSTING_CONFIRMED_SUCCESS, POSTING_CONFIRMED_FAILURE.

PageMetadata

Name Type Format Description
size int32 - Total number of pages returned.
totalElements int32 - Total count of records returned.
totalPages int32 - Total number of pages returned.
number int32 - Page location for which the result is returned, for example: first page starts with 0, second page starts with 1.
Name Type Format Description
rel string - Relation of link, for example: first, self, next, last.
href string - Complete URL for the paginated link.
hreflang string - Link language, if any.
media string - Media type, if any.
title string - Link title, if any.
type string - Link type, if any.
deprecation string - Deprecated indication, if any.

AcknowledgeRequest

Name Type Format Description
ids Array string The unique identifiers list for the financial documents.
systemId string - The external System ID that acknowledged the documents.

AcknowledgeResponse

Name Type Format Description
AcknowledgeResponse array AcknowledgeResponseItem The JSON response.

AcknowledgeResponseItem

Name Type Format Description
acknowledgeResult string - Acknowledge processing result. Supported values are: SUCCESS or FAILURE.
code Int32 Service Codes The Financial Integration Service Code. This is a particular code based on the success and failure of individual records for Acknowledging documents.
docId string - The financial document unique identifier. Maximum 32 chars.
errorMessage string - The error message, if any.
systemId string - The external system ID that acknowledged the documents. Maximum 50 chars.

Confirmation Request

Name Type Format Description
systemId string - Required The external system ID that acknowledged the documents, it can be an empty string. Maximum 50 chars.
postingConfirmations Array Posting Confirmation request item Posting confirmations JSON request.

Posting Confirmation Request Item

Name Type Format Description
docId string - The financial document ID to confirm. Maximum 32 chars.
overallPostingStatusCode string - Posting status. VALUES: error or success.
postingDocs array Posting Documents Details Posting documents details, if any.
systemMessages array System Messages Messages to post to SAP Concur, if any.

Posting Documents Details

Name Type Format Description
companyId string - Required External system organizational unit ID. Maximum 32 chars.
documentNumber string - External system document identifier. Maximum 80 chars.
fiscalYear int32 - External system fiscal year.
paymentRelevantLineItems array - Payment relevant line items. This array is usually empty.
postingDate string YYYY-MM-DD External system posting date.

System Messages

Name Type Format Description
concurTransactionLineItemId string - Report relevant line item id.
messageId string - External System message identifier.
messageLanguage string - Message Language code, example EN, FR.
messageLongText array - Message text, will be posted on the audit trail in SAP Concur.
messageShortText string - Message text, will be posted on the audit trail in SAP Concur.

Posting Confirmation Response

Name Type Format Description
PostingConfirmationResponse array Posting Confirmation Response Item The JSON response body.

PostingConfirmationResponseItem

Name Type Format Description
postingConfirmationResult string - Posting confirmation result. Supported values are: SUCCESS, SYSTEM_ERROR_OCCURRED, NOT_YET_ACKNOWLEDGED, DOCUMENT_NOT_FOUND, FAILURE, WAS_RECALLED.
detailMessage string - Posting confirmation message.
code Int32 - The Financial Service return code.
docId string - The document ID. Maximum 32 chars.
errorMessage string - The error message, if any.
systemId string - The external system ID that acknowledged the document. Maximum 50 chars.

Payment Confirmation Request

Name Type Format Description
systemId string - Required The external system ID that acknowledged the documents, it can be an empty string. Maximum 50 chars.
processingConfirmation Array Payment Confirmation Request Item Payment confirmations JSON request.

Payment Confirmation Request Item

Name Type Format Description
docId string - The financial document ID to confirm. Maximum 32 chars.
processingStatusCode string - Payment status. VALUES: CP, PP, RE, OB (Completely Paid, Partially paid, Reversal, Obsolete). Maximum 3 chars.
additionalMessage string - Reversal message or obsolete message if any.
clearingDetails array Payment Documents Details Payment documents details, if any.

Payment Documents Details

Name Type Format Description
clearingDate string - Date the payment cleared.
clearingAmount double - Amount cleared.
clearingCurrency string - Currency value.
receiver array Receiver Details Receiver details.
clearingReference array Clearing Reference Details Clearing reference details.

Receiver Details

Name Type Format Description
receiverId string - Receiver id
receiverName double - Name of receiver
receiverType string - Type of receiver

Clearing Reference Details

Name Type Format Description
companyCode string - Company code.
financialDocumentId string - Document ID in ERP.
fiscalYear string - Fiscal year.
paymentRef string - Payment reference ID.
paymentMethod string - Payment method Where E=Electronic Fund Transfer or C = Check.

Payment Confirmation Response

Name Type Format Description
PaymentConfirmationResponse array Payment Confirmation Response Item The JSON response body

PaymentConfirmationResponseItem

Name Type Format Description
paymentConfirmationResult string - Payment confirmation result. Supported values are: SUCCESS, SYSTEM_ERROR_OCCURRED, NOT_POSTING_CONFIRMED, DOCUMENT_NOT_FOUND, FAILURE, NOOP.
paymentRef string - Any message corresponding to payment reference being processed.
detailMessage string - Payment confirmation message.
code Int32 - The financial service return code.
docId string - The document ID. Maximum 32 chars.
errorMessage string - The error message, if any.
systemId string - The external system ID that acknowledged the document. Maximum 50 chars.

Example Financial Documents

Expense

{
   "employee": {
      "employeeFirstName": "FirstName",
      "employeeLastName": "LastName",
      "employeeId": "12345AB",
      "employeeMI": null,
      "employeeOrgUnit4Value": null,
      "employeeOrgUnit5Value": null,
      "employeeOrgUnit6Value": null,
      "employeeCustom1Code": null,
      "employeeCustom2Code": null,
      "employeeCustom3Code": null,
      "employeeCustom4Code": "001",
      "employeeCustom5Code": "USPUG",
      "employeeCustom6Code": "1234",
      "employeeCustom7Code": null,
      "employeeCustom8Code": null,
      "employeeCustom9Code": null,
      "employeeCustom10Code": null,
      "employeeCustom11Code": null,
      "employeeCustom12Code": null,
      "employeeCustom13Code": null,
      "employeeCustom14Code": null,
      "employeeCustom15Code": null,
      "employeeCustom16Code": "N",
      "employeeCustom17Code": null,
      "employeeCustom18Code": null,
      "employeeCustom19Code": null,
      "employeeCustom20Code": null,
      "employeeCustom21Code": "US Group",
      "employeeCustom1Value": null,
      "employeeCustom2Value": null,
      "employeeCustom3Value": null,
      "employeeCustom4Value": "US Inc.",
      "employeeCustom5Value": "US Publishing",
      "employeeCustom6Value": "Operations",
      "employeeCustom7Value": null,
      "employeeCustom8Value": null,
      "employeeCustom9Value": null,
      "employeeCustom10Value": null,
      "employeeCustom11Value": null,
      "employeeCustom12Value": null,
      "employeeCustom13Value": null,
      "employeeCustom14Value": null,
      "employeeCustom15Value": null,
      "employeeCustom16Value": null,
      "employeeCustom17Value": null,
      "employeeCustom18Value": null,
      "employeeCustom19Value": null,
      "employeeCustom20Value": null,
      "employeeCustom21Value": "US Group",
      "employeeOrgUnit1Code": null,
      "employeeOrgUnit2Code": null,
      "employeeOrgUnit3Code": null,
      "employeeOrgUnit4Code": null,
      "employeeOrgUnit5Code": null,
      "employeeOrgUnit6Code": null,
      "employeeOrgUnit1Value": null,
      "employeeOrgUnit2Value": null,
      "employeeOrgUnit3Value": null
   },
   "report": {
      "reportKey": 345,
      "ledgerCode": "DEFAULT",
      "reportId": "D0719B539ED64FE612AB",
      "totalApprovedAmount": 200,
      "reportName": "Trip to Minneapolis",
      "isTest": "N",
      "reportStartDate": null,
      "reportEndDate": null,
      "employeeCurrencyAlphaCode": "USD",
      "payrollPayIndicator": "N",
      "payrollPaymentClearingAccountCode": null,
      "cashAdvanceReturnsAmount": 0E-8,
      "revisionNumber": "1",
      "versionId": "4",
      "homeCountryCode": "US",
      "reportCustom20Code": null,
      "reportCustom1Value": null,
      "reportCustom2Value": null,
      "reportCustom3Value": null,
      "reportCustom4Value": null,
      "reportCustom5Value": null,
      "reportCustom6Value": null,
      "reportCustom7Value": null,
      "reportCustom8Value": null,
      "reportCustom9Value": null,
      "reportCustom10Value": null,
      "reportCustom11Value": null,
      "reportCustom12Value": null,
      "reportCustom13Value": null,
      "reportCustom14Value": null,
      "reportCustom15Value": "US Group",
      "reportCustom16Value": null,
      "reportCustom17Value": null,
      "reportCustom18Value": null,
      "reportCustom19Value": null,
      "reportCustom20Value": null,
      "reportOrgUnit1Code": null,
      "reportOrgUnit2Code": null,
      "reportOrgUnit3Code": null,
      "reportOrgUnit4Code": null,
      "reportOrgUnit5Code": null,
      "reportOrgUnit6Code": null,
      "reportOrgUnit1Value": null,
      "reportOrgUnit2Value": null,
      "reportCustom5Code": null,
      "reportCustom6Code": null,
      "reportCustom7Code": null,
      "reportCustom8Code": null,
      "reportCustom9Code": null,
      "reportCustom10Code": null,
      "reportCustom11Code": null,
      "reportCustom12Code": null,
      "reportCustom13Code": null,
      "reportCustom14Code": null,
      "reportCustom15Code": "US Group",
      "reportCustom16Code": "12345AB",
      "reportCustom17Code": null,
      "reportCustom18Code": null,
      "reportCustom19Code": null,
      "reportSubmitDate": "2018-03-02T18:12:03.050Z",
      "reportUserDefinedDate": "2018-03-02T00:00:00.000Z",
      "reportPaymentProcessingDate": "2018-03-02T18:34:30.260Z",
      "reportCreationDate": "2018-03-02T18:08:37.887Z",
      "reportCustom1Code": "12345AB",
      "reportCustom2Code": null,
      "reportCustom3Code": null,
      "reportCustom4Code": null,
      "reportOrgUnit3Value": null,
      "reportOrgUnit4Value": null,
      "reportOrgUnit5Value": null,
      "reportOrgUnit6Value": null
   },
   "expenseEntry": [
      {
         "cardProgramTypeCode": null,
         "entryCustom20Code": null,
         "entryCustom21Code": null,
         "entryCustom22Code": null,
         "entryCustom23Code": null,
         "entryCustom24Code": null,
         "entryCustom25Code": null,
         "entryCustom26Code": null,
         "entryCustom27Code": null,
         "entryCustom28Code": null,
         "entryCustom29Code": null,
         "entryCustom30Code": null,
         "entryCustom31Code": null,
         "entryCustom32Code": null,
         "entryCustom33Code": null,
         "entryCustom34Code": null,
         "entryCustom35Code": "US",
         "entryCustom36Code": null,
         "entryCustom37Code": null,
         "entryCustom38Code": null,
         "entryCustom39Code": "0.00000000",
         "entryCustom40Code": "200.00000000",
         "reportEntryTransactionAmount": 200,
         "entryLocationCityName": "Minneapolis",
         "entryCountrySubCode": "US-MN",
         "entryIsBillable": "N",
         "entryOrgUnit1Code": null,
         "entryOrgUnit2Code": null,
         "entryOrgUnit3Code": null,
         "entryOrgUnit4Code": null,
         "entryOrgUnit5Code": null,
         "entryOrgUnit6Code": null,
         "offsetPayType": "N",
         "entryCountryCode": "US",
         "entryUuid": null,
         "entrySupplierTaxID": null,
         "entryCustom1Code": null,
         "entryCustom2Code": null,
         "entryCustom3Code": null,
         "entryCustom4Code": null,
         "entryCustom5Code": null,
         "entryCustom6Code": null,
         "entryCustom7Code": null,
         "entryCustom8Code": null,
         "entryCustom9Code": null,
         "entryCustom10Code": null,
         "entryCustom11Code": null,
         "entryCustom12Code": null,
         "entryCustom13Code": null,
         "entryCustom14Code": null,
         "entryCustom15Code": null,
         "entryCustom16Code": null,
         "entryCustom17Code": null,
         "entryCustom18Code": null,
         "entryCustom19Code": null,
         "cardAccountID": null,
         "cardTransactionID": null,
         "cardTransactionAmount": null,
         "cardTransactionCurrency": null,
         "cardTransactionPostedAmount": null,
         "cardTransactionPostedCurrency": null,
         "clearingAccountCode": null,
         "entryApprovedAmount": 200,
         "expensePayIndicator": "N",
         "entryId": "A92F3AD820F4E546800515258C3E0893",
         "entryDescription": "",
         "entryVendorCode": "Astron Hotels",
         "entryCustom1Value": null,
         "entryCustom2Value": null,
         "entryCustom3Value": null,
         "entryCustom4Value": null,
         "entryCustom5Value": null,
         "entryCustom6Value": null,
         "entryCustom7Value": null,
         "entryCustom8Value": null,
         "entryCustom9Value": null,
         "entryCustom10Value": null,
         "entryCustom11Value": null,
         "entryCustom12Value": null,
         "entryCustom13Value": null,
         "entryCustom14Value": null,
         "entryCustom15Value": null,
         "entryCustom16Value": null,
         "entryCustom17Value": null,
         "entryCustom18Value": null,
         "entryCustom19Value": null,
         "entryCustom20Value": null,
         "entryCustom21Value": null,
         "entryCustom22Value": null,
         "entryCustom23Value": null,
         "entryCustom24Value": null,
         "entryCustom25Value": null,
         "entryCustom26Value": null,
         "entryCustom27Value": null,
         "entryCustom28Value": null,
         "entryCustom29Value": null,
         "entryCustom30Value": null,
         "entryCustom31Value": null,
         "entryCustom32Value": null,
         "entryCustom33Value": null,
         "entryCustom34Value": null,
         "entryCustom35Value": null,
         "entryCustom36Value": null,
         "entryCustom37Value": null,
         "entryCustom38Value": null,
         "entryCustom39Value": null,
         "entryCustom40Value": null,
         "entryOrgUnit1Value": null,
         "entryOrgUnit2Value": null,
         "entryOrgUnit3Value": null,
         "entryOrgUnit4Value": null,
         "entryOrgUnit5Value": null,
         "entryOrgUnit6Value": null,
         "entryLocationName": "Minneapolis",
         "entryReceiptId": "E921EECCBCBA393EAC5A9212DCE57D9B",
         "entryElectronicReceiptId": null,
         "allocation": [
            {
               "allocationId": "76A1774FEC7D0C4981FBB332AB5671A3",
               "allocationCustom1Code": "",
               "allocationCustom2Code": "",
               "allocationCustom3Code": "",
               "allocationCustom4Code": null,
               "allocationCustom5Code": null,
               "allocationCustom6Code": null,
               "allocationCustom7Code": null,
               "allocationCustom8Code": null,
               "allocationCustom9Code": null,
               "allocationCustom10Code": null,
               "allocationCustom11Code": null,
               "allocationCustom12Code": null,
               "allocationCustom13Code": null,
               "allocationCustom14Code": null,
               "allocationCustom15Code": null,
               "allocationCustom16Code": null,
               "allocationCustom17Code": null,
               "allocationCustom18Code": null,
               "allocationCustom19Code": null,
               "allocationCustom20Code": null,
               "allocationCustom1Value": null,
               "allocationCustom2Value": null,
               "allocationCustom3Value": null,
               "allocationCustom4Value": null,
               "allocationCustom5Value": null,
               "allocationCustom6Value": null,
               "allocationCustom7Value": null,
               "allocationCustom8Value": null,
               "allocationCustom9Value": null,
               "allocationCustom10Value": null,
               "allocationCustom11Value": null,
               "allocationCustom12Value": null,
               "allocationCustom13Value": null,
               "allocationCustom14Value": null,
               "allocationCustom15Value": null,
               "allocationCustom16Value": null,
               "allocationCustom17Value": null,
               "allocationCustom18Value": null,
               "allocationCustom19Value": null,
               "allocationCustom20Value": null,
               "allocationPercentage": 100,
               "journal": [
                  {
                     "amountGrossCard": null,
                     "journalAccountCode": "125ABC",
                     "journalPayee": "EMPL",
                     "journalPayer": "COMP",
                     "cardTransactionReferenceNumber": null,
                     "amountNetOfReclaim": 150,
                     "amountNetOfTax": 150,
                     "amountGross": 150,
                     "taxGuid": [],
                     "accountingTransactionType": null
                  },
                  {
                     "amountGrossCard": null,
                     "journalAccountCode": "12345",
                     "journalPayee": "EMPL",
                     "journalPayer": "COMP",
                     "cardTransactionReferenceNumber": null,
                     "amountNetOfReclaim": 50,
                     "amountNetOfTax": 50,
                     "amountGross": 50,
                     "taxGuid": [],
                     "accountingTransactionType": null
                  }
               ],
               "tax": []
            }
         ],
         "entryReceiptType": "N",
         "entryExchangeRateDirection": "M",
         "entryIsPersonal": "N",
         "entryVendorDescription": "Astron Hotels",
         "legacyEntryId": 294,
         "liabilityAccountCode": null,
         "expenseTypeName": "Hotel",
         "entryDate": "2018-02-17T00:00:00.000Z",
         "entryCurrAlphaCode": "USD",
         "entryExchangeRate": 1,
         "expenseTypeCode": "LODNG",
         "cardStatementPeriodStartDate": null,
         "cardStatementPeriodEndDate": null,
         "reportEntryPatKey": "CASH"
      }
   ],
   "cashAdvanceApplication": [
      {
         "cashAdvanceClearingAccountCode": "12345",
         "cashAdvanceId": "6A107A548D1B4B49BBF370DF02EC890D",
         "cashAdvanceApplicationAmount": -50,
         "cashAdvanceTransactionType": 2
      }
   ]
}

Example - Invoice

{
   "requestHeader":{
      "ledgerCode":"DEFAULT",
      "clearingAccountCode":null,
      "invoiceDate":"08/08/2018",
      "reqKey":35,
      "postingDate":null,
      "poNumber":null,
      "isTest":"N",
      "deliverySlipNumber":null,
      "discountPercentage":null,
      "paymentDueDate":"09/07/2018",
      "requestId":"9B1D30723CBF4F86A574",
      "requestOrgUnit4Code":null,
      "requestOrgUnit5Code":null,
      "requestOrgUnit6Code":null,
      "currencyAlphaCode":"USD",
      "ledgerName":"DEFAULT",
      "vendorInvoiceNumber":"25688",
      "multiplePurchaseOrder":"N",
      "invoicePayIndicator":"N",
      "payMethodType":"CLIENT",
      "submitDate":"2018-09-05T03:37:42.923Z",
      "requestTotal":50.00000000,
      "revisionNumber":"1",
      "processCompleteDate":null,
      "invoiceReceivedDate":null,
      "requestOrgUnit1Value":null,
      "requestOrgUnit2Value":null,
      "requestOrgUnit3Value":null,
      "requestOrgUnit4Value":null,
      "requestOrgUnit5Value":null,
      "requestOrgUnit6Value":null,
      "versionId":"4",
      "requestOrgUnit1Code":null,
      "requestOrgUnit2Code":null,
      "requestOrgUnit3Code":null,
      "requestCustom21Code":null,
      "requestCustom22Code":null,
      "requestCustom1Value":null,
      "requestCustom2Value":null,
      "requestCustom3Value":null,
      "requestCustom4Value":null,
      "requestCustom5Value":null,
      "requestCustom6Value":null,
      "requestCustom7Value":null,
      "requestCustom8Value":null,
      "requestCustom9Value":null,
      "requestCustom10Value":"Default-Change to Client",
      "requestCustom11Value":null,
      "requestCustom12Value":null,
      "requestCustom13Value":null,
      "requestCustom14Value":null,
      "requestCustom15Value":null,
      "requestCustom16Value":null,
      "requestCustom17Value":null,
      "requestCustom18Value":null,
      "requestCustom19Value":null,
      "requestCustom20Value":null,
      "requestCustom21Value":null,
      "requestCustom22Value":null,
      "requestCustom23Value":null,
      "requestCustom24Value":null,
      "amountNetInvoice":50.00000000,
      "amountShippingTotal":0E-8,
      "requestTitle":"FIS Test",
      "discountTermsDays":null,
      "requestCustom1Code":null,
      "requestCustom2Code":null,
      "requestCustom3Code":null,
      "requestCustom4Code":null,
      "requestCustom5Code":null,
      "requestCustom6Code":null,
      "requestCustom7Code":null,
      "requestCustom8Code":null,
      "requestCustom9Code":null,
      "requestCustom10Code":"Default",
      "requestCustom11Code":null,
      "requestCustom12Code":null,
      "requestCustom13Code":null,
      "requestCustom14Code":null,
      "requestCustom15Code":null,
      "requestCustom16Code":null,
      "requestCustom17Code":null,
      "requestCustom18Code":null,
      "requestCustom19Code":null,
      "requestCustom20Code":null,
      "requestCustom24Code":null,
      "netPaymentTermDays":"30",
      "requestCreationDate":"2018-09-05T03:37:00.143Z",
      "requestCustom23Code":null,
      "requestDescription":null
   },
   "ownerEmployee":{
      "employeeCustom20Value":null,
      "employeeCustom21Value":"System",
      "employeeCustom10Code":"Default",
      "employeeOrgUnit1Code":null,
      "employeeOrgUnit2Code":null,
      "employeeOrgUnit3Code":null,
      "employeeOrgUnit4Code":null,
      "employeeOrgUnit5Code":null,
      "employeeOrgUnit6Code":null,
      "employeeOrgUnit1Value":null,
      "employeeOrgUnit2Value":null,
      "employeeOrgUnit3Value":null,
      "employeeOrgUnit4Value":null,
      "employeeOrgUnit5Value":null,
      "employeeOrgUnit6Value":null,
      "employeeCustom1Code":"ext-record-4",
      "employeeCustom2Code":null,
      "employeeCustom3Code":null,
      "employeeCustom4Code":null,
      "employeeCustom5Code":null,
      "employeeCustom6Code":null,
      "employeeCustom7Code":null,
      "employeeCustom8Code":null,
      "employeeCustom9Code":"28",
      "employeeCustom11Code":null,
      "employeeCustom13Code":null,
      "employeeCustom14Code":null,
      "employeeCustom15Code":null,
      "employeeCustom16Code":"N",
      "employeeCustom17Code":null,
      "employeeCustom18Code":null,
      "employeeCustom19Code":null,
      "employeeCustom20Code":null,
      "employeeCustom21Code":"SYS",
      "employeeCustom1Value":null,
      "employeeCustom2Value":null,
      "employeeCustom3Value":null,
      "employeeCustom4Value":null,
      "employeeCustom5Value":null,
      "employeeCustom6Value":null,
      "employeeCustom7Value":null,
      "employeeCustom8Value":null,
      "employeeCustom9Value":"522 Product",
      "employeeCustom10Value":"Default-Change to Client",
      "employeeCustom11Value":null,
      "employeeCustom12Value":null,
      "employeeCustom13Value":null,
      "employeeCustom14Value":null,
      "employeeCustom15Value":null,
      "employeeCustom16Value":null,
      "employeeCustom17Value":null,
      "employeeCustom18Value":null,
      "employeeCustom19Value":null,
      "employeeId":"12345AB",
      "employeeMI":"C",
      "employeeFirstName":"FirstName",
      "employeeLastName":"LastName",
      "employeeCustom12Code":null
   },
   "vendor":{
      "vendorName":"Test Vendor",
      "vendorCode":"94F538F2C3224C6E871CFED9F0F8333A",
      "vendorShipFromAddressCode":null,
      "vendorRemitToAddressCode":"333",
      "vendorContactFirstName":null,
      "vendorContactLastName":null
   },
   "lineItem":[
      {
         "allocation":[
            {
               "journal":{
                  "accountCode":"MATER",
                  "amountShipping":0,
                  "amountNet":50.00,
                  "amountGross":50.00,
                  "tax":null
               },
               "allocationAccountCode":"MATER",
               "allocationCustom6Code":null,
               "allocationCustom7Code":null,
               "allocationCustom8Code":null,
               "allocationCustom9Code":null,
               "allocationCustom10Code":null,
               "allocationCustom11Code":null,
               "allocationCustom12Code":null,
               "allocationCustom13Code":null,
               "allocationCustom14Code":null,
               "allocationCustom15Code":null,
               "allocationCustom16Code":null,
               "allocationCustom17Code":null,
               "allocationCustom18Code":null,
               "allocationCustom19Code":null,
               "allocationCustom20Code":null,
               "allocationCustom1Code":"",
               "allocationCustom2Code":"",
               "allocationCustom3Code":"",
               "allocationCustom4Code":null,
               "allocationCustom5Code":null,
               "allocationPercentage":100.00000000,
               "allocationCustom1Value":null,
               "allocationCustom2Value":null,
               "allocationCustom3Value":null,
               "allocationCustom4Value":null,
               "allocationCustom5Value":null,
               "allocationCustom6Value":null,
               "allocationCustom7Value":null,
               "allocationCustom8Value":null,
               "allocationCustom9Value":null,
               "allocationCustom10Value":null,
               "allocationCustom11Value":null,
               "allocationCustom12Value":null,
               "allocationCustom13Value":null,
               "allocationCustom14Value":null,
               "allocationCustom15Value":null,
               "allocationCustom16Value":null,
               "allocationCustom17Value":null,
               "allocationCustom18Value":null,
               "allocationCustom19Value":null,
               "allocationCustom20Value":null,
               "allocationKey":158
            }
         ],
         "receiptNumbers":[

         ],
         "expenseTypeName":"Material",
         "poLineNumber":null,
         "externalLineItemId":null,
         "expenseTypeCode":"2000   ",
         "lineItemPurchaseOrderNumber":null,
         "lineItemCode":null,
         "lineItemDeliverySlipNumber":null,
         "lineItemUnitPrice":50.00000000,
         "lineItemSequenceOrder":1,
         "lineItemQuantity":1.00000000,
         "lineItemCustom1Value":null,
         "lineItemCustom2Value":null,
         "lineItemCustom3Value":null,
         "lineItemCustom4Value":null,
         "lineItemCustom5Value":null,
         "lineItemCustom6Value":null,
         "lineItemCustom7Value":null,
         "lineItemCustom8Value":null,
         "lineItemCustom9Value":null,
         "lineItemCustom10Value":null,
         "lineItemCustom11Value":null,
         "lineItemCustom12Value":null,
         "lineItemCustom13Value":null,
         "lineItemCustom14Value":null,
         "lineItemCustom15Value":null,
         "lineItemCustom16Value":null,
         "lineItemCustom17Value":null,
         "lineItemCustom18Value":null,
         "lineItemCustom19Value":null,
         "lineItemCustom20Value":null,
         "lineItemCustom1Code":null,
         "lineItemCustom2Code":null,
         "lineItemCustom3Code":null,
         "lineItemCustom4Code":null,
         "lineItemCustom5Code":null,
         "lineItemCustom6Code":null,
         "lineItemCustom7Code":null,
         "lineItemCustom8Code":null,
         "lineItemCustom9Code":null,
         "lineItemCustom10Code":null,
         "lineItemCustom11Code":null,
         "lineItemCustom12Code":null,
         "lineItemCustom13Code":null,
         "lineItemCustom14Code":null,
         "lineItemCustom15Code":null,
         "lineItemCustom16Code":null,
         "lineItemCustom17Code":null,
         "lineItemCustom18Code":null,
         "lineItemCustom19Code":null,
         "lineItemCustom20Code":null,
         "lineItemDescription":"Merchandise"
      }
   ]
}

Example - Cash Advance

{
   "employeeData": {
      "employeeFirstName": "FirstName",
      "employeeLastName": "LastName",
      "employeeId": "12345ID",
      "employeeMI": null,
      "employeeOrgUnit5Code": null,
      "employeeOrgUnit6Code": null,
      "employeeOrgUnit1Value": null,
      "employeeOrgUnit2Value": null,
      "employeeOrgUnit3Value": null,
      "employeeOrgUnit4Value": null,
      "employeeOrgUnit5Value": null,
      "employeeOrgUnit6Value": null,
      "employeeCustom1Code": null,
      "employeeCustom2Code": null,
      "employeeCustom3Code": null,
      "employeeCustom4Code": "001",
      "employeeCustom5Code": "ABUFG",
      "employeeCustom6Code": "2567",
      "employeeCustom7Code": null,
      "employeeCustom8Code": null,
      "employeeCustom9Code": null,
      "employeeCustom10Code": null,
      "employeeCustom11Code": null,
      "employeeCustom13Value": null,
      "employeeCustom14Value": null,
      "employeeCustom15Value": null,
      "employeeCustom16Value": null,
      "employeeCustom17Value": null,
      "employeeCustom18Value": null,
      "employeeCustom19Value": null,
      "employeeCustom20Value": null,
      "employeeCustom21Value": "US Group",
      "employeeCustom12Code": null,
      "employeeCustom13Code": null,
      "employeeCustom14Code": null,
      "employeeCustom15Code": null,
      "employeeCustom16Code": "N",
      "employeeCustom17Code": null,
      "employeeCustom18Code": null,
      "employeeCustom19Code": null,
      "employeeCustom20Code": null,
      "employeeCustom21Code": "US Group",
      "employeeCustom1Value": null,
      "employeeCustom2Value": null,
      "employeeCustom3Value": null,
      "employeeCustom4Value": "US Inc.",
      "employeeCustom5Value": "US Publishing",
      "employeeCustom6Value": "Operations",
      "employeeCustom7Value": null,
      "employeeCustom8Value": null,
      "employeeCustom9Value": null,
      "employeeCustom10Value": null,
      "employeeCustom11Value": null,
      "employeeCustom12Value": null,
      "employeeOrgUnit1Code": null,
      "employeeOrgUnit2Code": null,
      "employeeOrgUnit3Code": null,
      "employeeOrgUnit4Code": null
   },
   "cashAdvanceData": {
      "locationName": null,
      "exchangeRate": 1,
      "countryCode": null,
      "currencyAlphaCode": "USD",
      "cashAdvanceId": "FE884EE31617CF4CABE36C7FC44512A1",
      "clearingAccountCode": null,
      "purpose": null,
      "paymentMethod": 0,
      "requestAmount": 150,
      "requestDate": "2018-03-03T02:16:51.363Z",
      "issuedDate": "2018-03-06T03:54:36.993Z",
      "isTest": "N",
      "countrySubCode": null,
      "requestedDisbursementDate": null,
      "travelStartDate": null,
      "travelEndDate": null,
      "currencyNumCode": "840",
      "expensePayIndicator": "N",
      "employeeCurrencyAlphaCode": "USD",
      "cardAccountID": null,
      "cardTransactionID": null,
      "cardTransactionAmount": null,
      "cardTransactionCurrency": null,
      "cardTransactionPostedAmount": null,
      "cardTransactionPostedCurrency": null,
      "transactionType": 1,
      "name": "Cash Advance Testing 3"
   },
   "journalData": [
      {
         "accountCode": "12345",
         "amount": 150,
         "payee": "EMPL",
         "debitOrCredit": "DR",
         "payer": "COMP",
         "paymentCode": "Cash"
      }
   ]
}

Use Cases-Financial Integration

Overview

The use case examples below illustrate expense scenarios and the related posting records. Posting records will vary based on app design. The use case documentation is not meant to be a comprehensive list of all use cases and expense scenarios. However, the JSON from the Financial Integration Service will provide all the required data to support the all potential financial use cases.

Simple Expense Posting Without Tax

Simple Out-of-Pocket Cash Expense

Description

Very simple expense report with only a few expense items without VAT, for example, US expense report.

Posting Example

Expense Report with one expense item: Taxi – USD 10

Posting Record

Account Debit Credit
Expense (Taxi) USD 10 -
Employee Vendor - USD 10

Standard Accounting Extract Details

JSON Example

Simple Out-of-Pocket Cash Credit

Description

The user receives a USD 50 cash rebate for a hotel stay that was fully reimbursed on a previous expense report. Being a good corporate citizen the user enters a single USD 50 cash credit transaction and assigns it to the Expense Type "Hotel." The expense is a legitimate business expense, not a personal expense. It is not itemized.

Posting Example

Posting Record

Account Debit Credit
Expense (Hotel) - USD 50
Employee Vendor USD 50 -

Standard Accounting Extract Details

JSON Example

Simple Personal Car Mileage Expense

Description

The user enters a single personal car mileage transaction for a round trip to the airport of 60 miles. The expense is a legitimate business expense, not a personal expense. It is not itemized.

Posting Example

Posting Record

Account Debit Credit
Expense (Mileage) USD 24.30 -
Employee Vendor - USD 24.30

Standard Accounting Extract Details

JSON Example

Travel Allowances – Company Specific Rate Greater Than Government Rate

Description

A German traveler receives meal per diems that are higher the legal rates. In this case he gets EUR 50 instead of the EUR 24 legal amount allowed for a full day. As a result the amount reimbursed to the employee over the legal daily rate is taxable to the employee.

Posting Example

Posting Record

Account Debit Credit
Expense (Meals) EUR 50 -
Employee Vendor (non-taxable) - EUR 24
Employee Vendor (taxable) - EUR 26

Standard Accounting Extract Details

JSON Example

VAT Handling

The SAP Concur system, when configured and applicable, will calculate the related VAT tax for a given transaction. This determination relies on the customer’s tax configuration and will vary by customer and country. The posting document will include all related VAT amounts that are calculated.

How the VAT is handled is determined based on the Tax Code customization in ERP and the related VAT use cases that the partner application supports.

Expense Posting With Single Tax Item

Description

Very simple expense report with only a few expense items with VAT, for example, German expense report.

Posting Example

The posting below is one example of how the expense gets recorded by the customer based on their ERP set up and requirements.

Expense Report with one expense item: Laundry – EUR 10 (including 16 % - EUR 1.60 VAT).

Posting Record

Account Debit Credit
Expense (amount net of tax) EUR 8.40 -
VAT EUR 1.60 -
Employee Vendor (gross amount) - EUR 10

JSON Example

Non-Deductible VAT

The SAP Concur system, when configured and applicable, will calculate the related VAT tax for a given transaction. In some cases, this tax is deductible if it meets certain country-based requirements. In other cases, it is not deductible. This determination relies on the customer’s tax configuration and will vary by customer and country. The posting document will include all related VAT amounts that are calculated.

How the VAT is handled is determined based on the Tax Code customizing in ERP and the related VAT use cases that the partner application supports.

Description

Very simple expense report with only a few expense items with VAT, for example, German expense report.

Posting Example

The posting below is one example of how the expense gets recorded by the customer based on their ERP set up and requirements.

Expense Report with one expense item: Gas – EUR 100 (including 15.97% - EUR 15.97 VAT)

Posting Record

Account Debit Credit
Expense (amount net of tax) EUR 84.03 -
Non-deductible VAT Expense EUR 15.97 -
Employee Vendor (gross amount) - EUR 100

JSON Example

Expense Posting With Multiple Tax Items

Description

For a country like Canada, with multiple tax jurisdictions the entry may have multiple tax lines representing calculated VAT for each jurisdiction. The posting document will include all related tax lines and corresponding tax amounts.

Posting Example

The posting below is one example of how the expense gets recorded by the customer based on their ERP set up and requirements.

Expense Report with one expense item: Local Phone – CAD 100 with multiple tax jurisdictions (for example, tax type 1, tax type 2).

Posting Record

Account Debit Credit
Expense (amount net of tax) 88.50 CAD -
Tax Type 1 CAD 4.42 -
Tax Type 2 CAD 7.08 -
Employee Vendor (gross amount) - CAD 100

JSON Example

Partially Deductible VAT

Description

In some cases it could be possible that the whole VAT amount is not deductible. This case has similar posting options as non-deductible VAT.

Posting Example

The posting below is one example of how the expense gets recorded by the customer based on their ERP set up and requirements.

For a hotel receipt of CAD 55 (including 11.5% - CAD 6.32 VAT) the VAT is only deductible by 50%.

Posting Record

Account Debit Credit
Expense (amount net of tax) CAD 48.68 -
VAT CAD 3.16 -
Non-deductible VAT CAD 3.16 -
Employee Vendor (gross amount) - CAD 55

JSON Example

Foreign Expense Report Without VAT

Description

The SAP Concur system, when configured and applicable, will calculate the related VAT tax for a given transaction. In some cases, this tax is deductible if it meets certain country-based requirements. In other cases, it is not deductible. This determination relies on the customer’s tax configuration and will vary by customer and country. The posting document will include all related VAT amounts that are calculated.

In case an employee from a country with VAT enters a foreign receipt and the included VAT is not claimable, the document has to be posted with a 0% VAT tax code. In SAP Concur this tax code is normally customized for the tax authority in the non-domestic code field. Again, this will vary based on the exact use case and customer’s tax configuration.

Posting Example

A UK employee submits an entry for a US-based training. In this case the posting document will include U.S tax included on the receipt and the posting will be handled in the ERP according to the desired posting record. It’s common that the posting record will include the tax amount as part of the overall expense (in this case Hotel) but a valid tax code with a 0% rate will also be included. This allows the customer to report on foreign taxes paid but which are not reclaimable.

The posting below is one example of how the expense gets recorded by the customer based on their ERP set up and requirements.

Posting Record

Account Debit Credit
Room Rate GBP 60.24 -
Hotel Tax GBP 20.08 -
Card Vendor - GBP 80.32

JSON Example

Itemization

Itemized Expense Items

Description

John flew to New York to meet with a client and stayed one night at the Marriot. An original receipt is split into several parts, for example, lodging costs per night, room tax, and breakfast. All items should be processed separately in the Journal Section, SAE, and JSON.

Posting Example

For a hotel receipt of USD 325 where the costs per night and other expenses should be posted separately.

Posting Record

Account Debit Credit
Room Rate USD 250 -
Room Tax USD 50 -
Breakfast 25 USD -
Employee Vendor - USD 325

Standard Accounting Extract Details

JSON Example

Cost Allocation

What is cost allocation? Allocation is defined as a part of cross-charging is the ability to assign cost of an expense to multiple organizational units such as department, cost center, project code, etc.

When allocating the expense across multiple cost centers, the user needs to pick the correct code from the most granular level which may be from the Expense Entry, Journal Entry, and/or Allocation Entry depending on whether or not the customer is configured to use the allocation fields. Cost center codes should NEVER be picked up from the Employee Entry section because an employee may have to charge another department for a percentage of a transaction.

Expense With Multiple Cost Allocations

Description

Similar to the itemized expense example, however, the breakfast cost is allocated between two different cost centers.

Posting Example

For a hotel receipt of USD 325 where the costs per night and other expenses should be posted separately.

Posting Record

Account Debit Credit
Room Rate USD 250 -
Room Tax USD 50 -
Breakfast 25 USD -
Employee Vendor - USD 325

Extract Details

Standard Accounting Extract Details

JSON Example

NOTE: The room rate and room tax is charged to the same cost center as in the itemized expense example. Only the breakfast cost is allocated 50% between two different cost centers: 0021-Bellevue1 and Top Management. The allocation section is towards the bottom of the JSON.

Cash Advances

Issuance

Description

An employee requests a cash advance to be paid in cash or via transfer.

Posting Example

Employee requests a cash advance of USD 7000 for trip to TechEd.

Posting Record

Account Debit Credit
Cash Advance Clearing Account USD 7000 -
Employee Vendor - USD 7000

Standard Accounting Extract Details

Note: This extract example is the same as Itemized Expense Items.

JSON Example

Application

Cash Advance Is Lower Than the Payout Amount

Description

The employee enters an expense report and assigns a cash advance. This cash advance reduces the employee’s payout amount. Only the difference between the sum of the expense items paid by the employee and the cash advance will be paid to the employee.

Posting Example

The user has requested and received an GBP 300 cash advance. In the course of travel the user incurs the following cash expenses: GBP 245 for a rental car, GBP 60 for a business meal, and GBP 10 for parking. After returning from travel the user finds the GBP 300 cash advance has been issued via the corporate card import process. He assigns the GBP 300 cash advance to an expense report and enters the three cash expenses and submits. The expenses are not itemized. The expenses are legitimate business expenses.

Posting Record

Account Debit Credit
Car Rental GBP 245 -
Meal GBP 60 -
Parking GBP 10 -
Cash Advance Clearing Account GBP 300 -
Employee Vendor - GBP 15

Extract Details

Standard Accounting Extract

JSON Example

Standard Accounting Extract

JSON Example

Cash Advance Is Higher Than the Payout Amount

Description

The employee enters an expense report and assigns a cash advance. If the cash advance is higher than the sum of the expense items paid by the employee the employee owes the difference to the company.

Posting Example

The user has requested and received a GBP 400 cash advance and during travel spends GBP245 on a rental car, GBP 60 on a business meal, and GBP 10 on parking. The user assigns the GBP 400 cash advance to the expense report and enters the three cash expenses and submits. The expenses are not itemized. The expenses are legitimate business expenses. Because the total of the cash advance exceeds the sum of the business expenses the net result of the expense report is that the employee owes the company the balance. The employee will write a check to the company for the balance (GBP 85) and enter a cash advance return transaction in that amount to net the expense report to zero.

Posting Record

Account Debit Credit
Car Rental GBP 245 -
Meals GBP 60 -
Parking GBP 10 -
Cash Advance Clearing Account - GBP 400
Employee Vendor GBP 85 -

Extract Details

Standard Accounting Extract

JSON Example

Standard Accounting Extract

JSON Example

Credit Card Types

Employee Paid Credit Card

Payment via Employee Vendor Account

Description

Credit card items with employee liability should be paid to the employee’s bank account like cash paid expenses. (IBIP)

Posting Example

Expense Report with one employee paid credit card item: Taxi - USD 10.

Posting Record

Account Debit Credit
Expense (Taxi) USD 10 -
Employee Vendor - USD 10

Standard Accounting Extract

JSON Example

Payment via Credit Card Vendor Account (Split Payment)

Description

Approved business expenses should be paid to the credit card instead of the employee’s bank account. (IBCP)

Posting Example

Car rental was paid with IBIP card for USD 56.10.

Posting Record

Account Debit Credit
Expense (Car Rental) USD 56.10 -
Credit Card Vendor - USD 56.10

Standard Accounting Extract

JSON Example

Credit Transaction via Credit Card Vendor Account (Split Payment)

Example

The user receives a USD 349 credit on the corporate card for an unused airline ticket. The credit transaction is displayed as a pre-populated corporate card transaction and the user selects it and submits an expense report. The expense is a legitimate business expense, not a personal expense. It is not itemized.

Posting

Posting Record

Account Debit Credit
Expense (Airfare) - USD 349
Credit Card Vendor USD 349 -

Standard Accounting Extract

JSON Example

Simple IBCP Corporate Card Charge With Itemization

Example

John flew to New York to meet with a client and stayed one night at the Marriot. An original receipt is split into several parts, for example, lodging costs per night, room tax, and breakfast. All items should be processed separately in the Journal Section, SAE, and JSON.

Posting Example

For a hotel receipt of USD 325 where the costs per night and other expenses should be posted separately.

Posting Record

Account Debit Credit
Room Rate USD 250 -
Room Tax USD 50 -
Breakfast USD 25 -
Employee Vendor - USD 325

Standard Accounting Extract

JSON Example

IBCP With Personal Expense: No Out-of-Pocket

NOTE: Personal expenses paid by an IBCP credit card will not be included in the JSON.

Example

John flew to New York to meet with a client and stayed one night at the Marriot. An original receipt is split into several parts, for example, lodging costs per night, room tax, and breakfast. All items should be processed separately in the Journal Section, SAE, and JSON. Since breakfast is a personal expense, it will be included in the extract but NOT in the JSON.

Posting Example

For a hotel receipt of USD 325 where the costs per night and other expenses should be posted separately.

Posting Record

Account Debit Credit
Room Rate USD 250 -
Room Tax USD 50 -
Breakfast (personal) USD 25 -
Employee Vendor - USD 325

Standard Accounting Extract

JSON Example

IBCP with Personal Expense Where Out-of-Pocket Exceeds the Personal Expense

NOTE: Personal expenses paid by an IBCP credit card will not be included in the JSON when a non-offsetting payment is used because it’s not relevant to the company’s accounting record.

Without Offsetting

Example

The user assigns a pre-populated corporate card transaction to the expense report. The transaction is a Hotel expense in the amount of USD 284. The hotel expense consists of a two-night stay at USD 125 per night and the user had a USD 20 dinner after checking in and ordered an in-room movie for USD 14 that the company does not reimburse for. The expense is itemized. The expense is a legitimate business expense with the exception of the in-room movie that the user marks as a non-reimbursable expense on the expense report. The expense report also includes an out-of-pocket cash transaction for a taxi at USD 35.

Posting

Posting Record

Account Debit Credit
Room Rate USD 125 -
Room Rate USD 125 -
Dinner USD 20 -
Taxi USD 35 -
Credit Card Vendor - USD 270
Employee Vendor - USD 35

JSON Example

With Offsetting

When using offsets the amount due the employee for out-of-pocket expenses is netted (or offset) against the amount marked as personal, resulting in an entry reflecting either the final amount the employee owes the company (assumes personal exceeds out of pocket) or final amount company owes the employee (reduced by any personal amounts).

Posting

Posting Record

Account Debit Credit
Room Rate USD 125 -
Room Rate USD 125 -
Dinner USD 20 -
Taxi USD 14 -
Taxi USD 21 -
Credit Card Vendor - USD 284
Employee Vendor - USD 21

Extract Details

Standard Accounting Extract

JSON Example

IBCP With Personal Expense Where Out-of-Pocket Is Less Than Personal Expense

NOTE: Personal expenses paid by an IBCP credit card will not be included in the JSON when a non-offsetting payment is used because it’s not relevant to the company’s accounting record.

Without Offsetting

Example

The user assigns a pre-populated corporate card transaction to the expense report. The transaction is a Hotel expense in the amount of USD 284. The hotel expense consists of a two-night stay at USD 125 per night and the user had a USD 20 dinner after checking in and ordered an in-room movie for USD 14 that the company does not reimburse for. The expense is itemized. The expense is a legitimate business expense with the exception of the in-room movie that the user marks as a non-reimbursable expense on the expense report. The expense report also includes an out-of-pocket cash transaction for parking in the amount of USD 5.

Posting

Posting Record

Account Debit Credit
Hotel USD 125 -
Hotel USD 125 -
Dinner USD 20 -
Parking USD 5 -
Credit Card Vendor - USD 275

JSON Example

With Offsetting

When using offsets the amount due the employee for out-of-pocket expenses is netted (or offset) against the amount marked as personal, resulting in an entry reflecting either the final amount the employee owes the company (assumes personal exceeds out of pocket) or final amount company owes the employee (reduced by any personal amounts).

Posting

Posting Record

Account Debit Credit
Hotel USD 125 -
Hotel USD 125 -
Dinner USD 20 -
Parking USD 5 -
Credit Card Vendor - USD 275

Standard Accounting Extract

JSON Example

Company Paid Credit Card

CBCP Corporate Card Charge for Entirely Personal Expense (Net Due Company With Consolidated or Verbose Extract)

Example

The employee mistakenly uses the corporate card to pay for tolls (USD 32) and dues (USD 49) expense totaling USD 81. When the corporate card transaction feed populates the company card page the employee must deal with this transaction. The employee assigns the USD 81 corporate card transaction to an expense report, marks it as a non-reimbursable expense and submits the report for approval.

Posting

Posting Record

Account Debit Credit
Employee Vendor USD 49 -
Credit Card Clearing - USD 49
Credit Card Clearing USD 49 -
Credit Card Vendor - USD 49
Employee Vendor USD 32 -
Credit Card Clearing - USD 32
Credit Card Clearing USD 32 -
Credit Card Vendor - USD 32

Standard Accounting Extract

JSON Example

CBCP Corporate Card Charge with Itemization and Personal Expense (Net Due Employee With Consolidation)

Example

The user assigns a pre-populated corporate card transaction to the expense report. The transaction is a Hotel expense in the amount of USD 284. The hotel expense consists of a two-night stay at USD 125 per night and the user had a USD 20 dinner after checking in and ordered an in-room movie for USD 14 that the company does not reimburse for. The expense is itemized. The expense is a legitimate business expense with the exception of the in-room movie that the user marks as a non-reimbursable expense on the expense report. The expense report also includes an out-of-pocket cash transaction for a taxi at USD 35.

Posting

Posting Record

Expense Report:

Account Debit Credit
Room Rate USD 125 -
Room Rate USD 125 -
Dinner USD 20 -
Taxi USD 32 -
Employee Vendor (personal expense) USD 14 -
Employee Vendor - USD 35
Credit Card Clearing - USD 284

Standard Accounting Extract

JSON Example

CBCP Corporate Card Charge for Entirely Personal Expense (Net Due Company With Verbose Extract)

Example

The employee mistakenly uses the corporate card to pay for a personal dinner expense of USD 300. When the corporate card transaction feed populates the company card page the employee must deal with this transaction. The employee assigns the USD 300 corporate card transaction to an expense report, marks it as a non-reimbursable expense and submits the report for approval.

Posting

Posting Record

Account Debit Credit
Employee Vendor USD 300 -
Credit Card Clearing Account - USD 300
Credit Card Clearing Account USD 300 -
Credit Card Vendor - USD 300

Standard Accounting Extract

JSON Example

CBCP Corporate Card Charge with Itemization and Personal Expense (Net Due Employee With No Offsets)

Example

The user assigns a pre-populated corporate card transaction to the expense report. The transaction is a Hotel expense in the amount of USD 284. The hotel expense consists of a two-night stay at USD 125 per night and the user had a USD 20 dinner after checking in and ordered an in-room movie for USD 14 that the company does not reimburse for. The expense is itemized. The expense is a legitimate business expense with the exception of the in-room movie that the user marks as a non-reimbursable expense on the expense report. The expense report also includes an out-of-pocket cash transaction for a taxi at USD 35.

Posting

Posting Record

Account Debit Credit
Room Rate USD 125 -
Room Rate USD 125 -
Dinner USD 20 -
Taxi USD 35 -
Employee Vendor (out of pocket) - USD 35
Employee Vendor (personal expense) USD 14 -
Credit Card Vendor - USD 284

Standard Accounting Extract

JSON Example

Use Cases Extract Information

Note: The extract file excerpts in this document are a reference point for those developers who have used those files for prior financial integrations. This excerpt is intended to help those developers transition from an extract file to the Financial Integration Service. This allows you to identify what you have been using from the extract file and to locate the same data in the new JSON response. If you have not used the extract file previously, the extract file excerpts can be skipped.

Simple Expense Posting Without Tax

Simple Out-of-Pocket Cash Expense

The Payer in this instance is the company; the Payee is the employee. Since it is not an itemized expense the Entry Transaction Type is REG. Because it is a legitimate business expense the ‘Is Personal’ flag is set to ‘N’. The employee will be reimbursed for this transaction.

[61] entry_id [64] Entry Transaction Date [70] Vendor Name [63] Expense Type [68] Is Personal [62] Entry Transaction Type [163] Payer Payment Type [165] Payee Payment Type [169] Journal Amount [168] Debit Credit [167] Account Code [177] Cash Advance Amount [185] Cash Advance Transaction Type
8337 03/05/2016 - Taxi N REG COMPANY EMPLOYEE USD 10 DR 474230 - -

Simple Out-of-Pocket Cash Credit

The Payer in this instance is the employee; the Payee is the company. Since it is not an itemized expense the Entry Transaction Type is REG. Because it is a legitimate business expense the ‘Is Personal’ flag is set to ‘N’. The company will be reimbursed for this transaction.

[61] entry_id [64] Entry Transaction Date [70] Vendor Name [63] Expense Type [68] Is Personal [62] Entry Transaction Type [163] Payer Payment Type [165] Payee Payment Type [169] Journal Amount [168] Debit Credit [167] Account Code [177] Cash Advance Amount [185] Cash Advance Transaction Type
4178 5/28/2019 Ritz Carlton Booking Fees (Hotel) N REG EMPLOYEE COMPANY USD -50 CR 5 - -

Simple Personal Car Mileage Expense

The Payer in this instance is the company; the Payee is the employee. Since it is not an itemized expense the Entry Transaction Type is REG. Because it is a legitimate business expense the ‘Is Personal’ flag is set to ‘N’. The employee will be reimbursed for this transaction.

[61] entry_id [64] Entry Transaction Date [70] Vendor Name [63] Expense Type [68] Is Personal [62] Entry Transaction Type [163] Payer Payment Type [165] Payee Payment Type [169] Journal Amount [168] Debit Credit [167] Account Code [177] Cash Advance Amount [185] Cash Advance Transaction Type
4173 5/23/2019 - Mileage N REG COMPANY EMPLOYEE USD 24.30 DR 54 - -

Travel Allowances: Company Specific Rate Greater Than Government Rate

The Payer in this instance is the company; the Payee is the employee. Since it is not an itemized expense the Entry Transaction Type is REG. Because it is a legitimate business expense the ‘Is Personal’ flag is set to ‘N’. The employee will be reimbursed for this transaction.

The report entry item will be split into 2 journal entry items: 1st item: amount up to the legal limit, 2nd item: amount above the legal limit.

[61] entry_id [64] Entry Transaction Date [70] Vendor Name [63] Expense Type [68] Is Personal [62] Entry Transaction Type [163] Payer Payment Type [165] Payee Payment Type [169] Journal Amount [168] Debit Credit [167] Account Code [177] Cash Advance Amount [185] Cash Advance Transaction Type
4196 5/28/2019 - Fixed Meals N REG COMPANY EMPLOYEE 24 EUR DR 474230 - -
4197 5/28/2019 - Fixed Meals N REG COMPANY EMPLOYEE 26 EUR DR 474230 - -

VAT Handling

Expense Posting With Single Tax Item

For the expense line: The Payer in this instance is the company; the Payee is the employee. Since it is not an itemized expense the Entry Transaction Type is REG. Because it is a legitimate business expense the ‘Is Personal’ flag is set to ‘N’. The employee will be reimbursed for this transaction. The Tax Code will also appear on this detail line along with the Tax Authority details (label and name).

Tax data: The appearance of the tax data in the extract is governed by the extract options to either include tax information in the same detail line as the entry on which tax is calculated, or to include it as a separate journal line. In this example tax is set to appear as a journal line. The payer is the notional tax authority with the payee as the company (as the reclaimed tax will eventually be paid by the tax authority to the company).

The Journal Amount on the tax detail line can be set to either list the amount eligible to reclaim on either the posted or adjusted (reclaim_posted_amount or reclaim_adjusted_amount). If ‘Adjusted’ the tax reclaim will be calculated on the approved amount (the approved amount may be lower than the claimed (posted) amount). The Tax Source identifies the source of the tax calculation.

The Tax Code can also be set to appear in the Account Code field on the tax detail line (instead of the account code), as shown in this example. The difference between the ‘reclaim’ fields (reclaim_tax_amount, reclaim_posted_amount, reclaim_adjusted_amount) and other tax amount fields (tax_amount, tax_posted_amount, etc.) is that ‘Reclaim’ indicates that these figures are subject to the reclaim percentage specified in the tax configuration.

[61] entry_id [64] Entry Transaction Date [63] Expense Type [68] Is Personal [62] Entry Transaction Type [163] Payer Payment Type [165] Payee Payment Type [169] Journal Amount [168] Debit Credit [167] Account Code [226] Tax Auth Label [227] Tax Amount [228] Tax Posted Amount [229] Tax Source [230] reclaim_tax_amount [231] reclaim_posted_amount [232] Tax Code [233] reclaim_domestic
4282 6/5/2019 Laundry N REG EMPLOYEE COMPANY 8.40 EUR DR 37 ILR 0 0 - 0 0 V1 -
4282 6/5/2019 Laundry N REG ILR COMPANY 1.60 EUR CR V1 ILR 1.60 1.60 SYST 1.60 1.60 V1 Y

Itemization

Itemized Expense Items

The Payer in this instance is the company; the Payee is the corporate card vendor. Since it is an itemized expense the Entry Transaction Type is CHD. Because it is a legitimate business expense the ‘Is Personal’ flag is set to ‘N’. Because this is an IBCP transaction and the payment will be made to the card vendor on behalf of the employee the employee will not receive reimbursement.

[61] entry_id [64] Entry Transaction Date [70] Vendor Name [63] Expense Type [68] Is Personal [62] Entry Transaction Type [163] Payer Payment Type [165] Payee Payment Type [169] Journal Amount [168] Debit Credit [167] Account Code [177] Cash Advance Amount [185] Cash Advance Transaction Type
4199 05/27/2019 All Suites International Hotel Room Rate N CHD COMPANY IBCP CORP USD 250 DR 474230 - -
4200 05/27/2019 All Suites International Hotel Tax N CHD COMPANY IBCP CORP USD 50 DR 474230 - -
4201 05/28/2019 All Suites International Breakfast N CHD COMPANY IBCP CORP USD 25 DR 474230 - -

Cash Advances

Issuance Extract (For reference only. Issuance is not included in the Expense Report FI Document)

There will be one issuance record for each cash advance issued. The issuance record can be identified by the Cash Advance Transaction Type which will always be a ‘1’. The Payer is the Company and the Payee is the Employee. The Journal Amount is a DR transaction in the reimbursement currency. The Cash Advance Amount is the amount of the cash advance in the currency of issuance. The Account Code is the employee cash advance account code, which is an element of the employee profile.

[61] entry_id [64] Entry Transaction Date [70] Vendor Name [63] Expense Type [68] Is Personal [62] Entry Transaction Type [163] Payer Payment Type [165] Payee Payment Type [169] Journal Amount [168] Debit Credit [167] Account Code [177] Cash Advance Amount [185] Cash Advance Transaction Type
- 3/7/2019 - - N - COMPANY EMPLOYEE USD 7000 DR 1009990 USD 7000 1

Cash Advance Is Lower Than the Payout Amount

Issuance Extract (For reference only. Issuance is not included in the Expense Report FI Document)

There will be one issuance record for each cash advance issued. The issuance record can be identified by the Cash Advance Transaction Type which will always be a ‘1’. The Payer is the Company and the Payee is the Employee. The Journal Amount is a DR transaction in the reimbursement currency. The Cash Advance Amount is the amount of the cash advance in the currency of issuance. The Account Code is the employee cash advance account code, which is an element of the employee profile.

[61] entry_id [64] Entry Transaction Date [70] Vendor Name [63] Expense Type [68] Is Personal [62] Entry Transaction Type [163] Payer Payment Type [165] Payee Payment Type [169] Journal Amount [168] Debit Credit [167] Account Code [177] Cash Advance Amount [185] Cash Advance Transaction Type
- 6/22/2019 - - N - COMPANY EMPLOYEE GBP 300 DR - GBP 300 1

The application of the CA issuance:

The application phase of this case will spawn five records in the standard extract file. Three of the records will cover the three cash out-of-pocket transactions. These three transactions are handled in the same way all cash, out-of-pocket transactions are handled (See the posting record above).

The two additional records are unique to an expense report containing a cash advance. The system will attempt to recover the cash advance amount from the employee by creating credit records against the cash transactions until the total of the cash advance is recovered. In this example, the first cash advance record (entry_id 61) credits the entire GBP 245 of its companion record (entry_id 58). That still leaves GBP 55 of the cash advance unrecovered. So another credit record (entry_id 62) in the amount of GBP 55 will be created against the next companion cash expense record (entry_id 59 and 60). At this point the GBP 300 cash advance has been recovered. The credit journal amounts have the effect of offsetting the total amount due the employee by the amount of the cash advance.

These offset records will have the following characteristics: the Payer is the employee; the Payee is the company. The debit/credit indicator will always be ‘CR’. The Cash Advance Amount field will always contain the total of the cash advances applied to the expense report. The Cash Advance Transaction Type will be a ‘2’. The employee will receive the net of the total cash expenses less the cash advance amount; in this example, GBP 15.

[61] entry_id [64] Entry Transaction Date [70] Vendor Name [63] Expense Type [68] Is Personal [62] Entry Transaction Type [163] Payer Payment Type [165] Payee Payment Type [169] Journal Amount [168] Debit Credit [167] Account Code [177] Cash Advance Amount [185] Cash Advance Transaction Type
58 6/21/2019 null Rental Car N REG COMPANY EMPLOYEE GBP 245 DR 109 - -
59 6/21/2019 Qdoba Dinner N REG COMPANY EMPLOYEE GBP 60 DR 105 - -
60 6/21/2019 Republic Parking Parking N REG COMPANY EMPLOYEE GBP 10 DR 130 - -
61 6/21/2019 - Rental Car N REG EMPLOYEE COMPANY GBP -245 CR 1009990 GBP 300 2
62 6/21/2019 - Dinner & Parking N REG EMPLOYEE COMPANY GBP -55 CR 1009990 GBP 300 2

Cash Advance Is Higher Than the Payout Amount

Issuance Extract (For reference only. Issuance is not included in the Expense Report FI Document)

There will be one issuance record for each cash advance issued. The issuance record can be identified by the Cash Advance Transaction Type which will always be a ‘1’. The Payer is the company and the Payee is the employee. The Journal Amount is a DR transaction in the reimbursement currency. The Cash Advance Amount is the amount of the cash advance in the currency of issuance. The Account Code is the employee cash advance account code, which is an element of the employee profile.

[61] entry_id [64] Entry Transaction Date [70] Vendor Name [63] Expense Type [68] Is Personal [62] Entry Transaction Type [163] Payer Payment Type [165] Payee Payment Type [169] Journal Amount [168] Debit Credit [167] Account Code [177] Cash Advance Amount [185] Cash Advance Transaction Type
- 6/22/2019 - - N - COMPANY EMPLOYEE GBP 400 DR - GBP 300 1

The application of the CA issuance:

The application phase of this case will spawn seven records in the standard extract file. Three of the records will cover the three cash out-of-pocket transactions. These three transactions are handled in the same way all cash, out-of-pocket transactions are handled (See the posting record above).

The four additional records are unique to an expense report containing a cash advance. The system will attempt to recover the cash advance amount from the employee by creating credit records against the cash transactions until the total of the cash advance is recovered. In this example, since the total of all expenses does not equal or exceed the cash advance amount, all three expense records have a corresponding offset credit. That still leaves the user GBP 85 short. The cash advance return record in the amount of a GBP 85 credit nets the cash advance amount to zero.

These offset records will have the following characteristics: the Payer is the employee; the Payee is the company. The debit/credit indicator will always be ‘CR’. The Cash Advance Amount field will always contain the total of the cash advances applied to the expense report. The Cash Advance Transaction Type will be a ‘2’. The employee will receive the net of the total cash expenses less the cash advance amount and in the case of a net due to company the employee will be required to submit a cash advance return to retire the balance owed; in this example, GBP 85.

[61] entry_id [64] Entry Transaction Date [70] Vendor Name [63] Expense Type [68] Is Personal [62] Entry Transaction Type [163] Payer Payment Type [165] Payee Payment Type [169] Journal Amount [168] Debit Credit [167] Account Code [177] Cash Advance Amount [185] Cash Advance Transaction Type
61 6/21/2019 AVIS Rental Car N REG COMPANY EMPLOYEE GBP 245 DR 109 - -
62 6/21/2019 MORTONS Business Meal N REG COMPANY EMPLOYEE GBP 60 DR 105 - -
63 6/21/2019 Republic Parking Parking N REG COMPANY EMPLOYEE GBP 10 DR 130 - -
- 6/21/2019 AVIS Rental Car N REG EMPLOYEE COMPANY GBP -245 CR 1009990 GBP 400 2
- 6/21/2019 MORTONS Business Meal N REG EMPLOYEE COMPANY GBP -60 CR 1009990 GBP 400 2
- 6/21/2019 Republic Parking Parking N REG EMPLOYEE COMPANY GBP -10 CR 1009990 GBP 400 2
- 6/21/2019 - Cash Advance Return N REG EMPLOYEE COMPANY GBP -85 CR 1009990 GBP 400 2

Credit Card Types

Payment via Employee Vendor Account

The Payer in this instance is the company; the Payee is the employee. Since it is not an itemized expense the Entry Transaction Type is REG. Because it is a legitimate business expense the ‘Is Personal’ flag is set to ‘N’. The employee will be reimbursed for this transaction.

[61] entry_id [64] Entry Transaction Date [70] Vendor Name [63] Expense Type [68] Is Personal [62] Entry Transaction Type [163] Payer Payment Type [165] Payee Payment Type [169] Journal Amount [168] Debit Credit [167] Account Code [177] Cash Advance Amount [185] Cash Advance Transaction Type
8337 03/05/2016 - Taxi N REG COMPANY EMPLOYEE USD 10 DR 474230 - -

Payment via Credit Card Vendor Account (Split Payment)

The Payer in this instance is the company; the Payee is the corporate card vendor. Since it is not an itemized expense the Entry Transaction Type is REG. Because it is a legitimate business expense the ‘Is Personal’ flag is set to ‘N’. Because this is an IBCP transaction and the payment will be made to the card vendor on behalf of the employee the employee will not receive reimbursement.

[61] entry_id [64] Entry Transaction Date [70] Vendor Name [63] Expense Type [68] Is Personal [62] Entry Transaction Type [163] Payer Payment Type [165] Payee Payment Type [169] Journal Amount [168] Debit Credit [167] Account Code [177] Cash Advance Amount [185] Cash Advance Transaction Type
36 4/7/2008 DOLLAR Rental Car N REG COMPANY IBCP CORP USD 56.10 DR 11 - -

Credit Transaction via Credit Card Vendor Account (Split Payment)

The Payer in this instance is the corporate card vendor; the Payee is the company. Since it is not an itemized expense the Entry Transaction Type is REG. Because it is a legitimate business expense the ‘Is Personal’ flag is set to ‘N’. Because this is an IBCP transaction and the payment/credit will be made to the card vendor on behalf of the employee the employee will not receive reimbursement (or be required to pay the balance).

[61] entry_id [64] Entry Transaction Date [70] Vendor Name [63] Expense Type [68] Is Personal [62] Entry Transaction Type [163] Payer Payment Type [165] Payee Payment Type [169] Journal Amount [168] Debit Credit [167] Account Code [177] Cash Advance Amount [185] Cash Advance Transaction Type
4225 5/27/2019 ALASKA AIRLINE Airfare N REG COPD COMPANY USD -349 CR 474230 - -

Simple IBCP Corporate Card Charge With Itemization

The Payer in this instance is the company; the Payee is the corporate card vendor. Since it is an itemized expense the Entry Transaction Type is ‘CHD’. Because it is a legitimate business expense the ‘Is Personal’ flag is set to ‘N’. Because this is an IBCP transaction and the payment will be made to the card vendor on behalf of the employee the employee will not receive reimbursement.

[61] entry_id [64] Entry Transaction Date [70] Vendor Name [63] Expense Type [68] Is Personal [62] Entry Transaction Type [163] Payer Payment Type [165] Payee Payment Type [169] Journal Amount [168] Debit Credit [167] Account Code [177] Cash Advance Amount [185] Cash Advance Transaction Type
4199 05/27/2019 All Suites International Hotel Room Rate N CHD COMPANY IBCP CORP USD 250 DR 474230 - -
4200 05/27/2019 All Suites International Hotel Tax N CHD COMPANY IBCP CORP USD 50 DR 474230 - -
4201 05/28/2019 All Suites International Breakfast N CHD COMPANY IBCP CORP USD 25 DR 474230 - -

IBCP With Personal Expense: No Out-of-Pocket

The Payer in this instance is the company; the Payee is the corporate card vendor. Since it is an itemized expense the Entry Transaction Type is CHD. Because this is an IBCP transaction and the payment will be made to the card vendor on behalf of the employee the employee will not receive reimbursement. Because the entry marked as personal is not a legitimate/approved business expense, payment to the card vendor is the responsibility of the employee. The amount is not reimbursable to the employee and the expense amount should not be posted with other business transactions. Therefore, the personal amount is not included in the financial posting JSON.

[61] entry_id [64] Entry Transaction Date [70] Vendor Name [63] Expense Type [68] Is Personal [62] Entry Transaction Type [163] Payer Payment Type [165] Payee Payment Type [169] Journal Amount [168] Debit Credit [167] Account Code [177] Cash Advance Amount [185] Cash Advance Transaction Type
4220 05/29/2019 All Suites International Hotel Room Rate N CHD COMPANY IBCP USD 250 DR 474230 - -
4221 05/29/2019 All Suites International Hotel Tax N CHD COMPANY IBCP USD 50 DR 474230 - -
4222 05/30/2019 All Suites International Breakfast Y REG EMPL COMPANY USD 25 DR 199999 - -

IBCP with Personal Expense Where Out-of-Pocket Exceeds the Personal Expense

The Payer for both transactions is the company. The Payee is the corporate card vendor for the legitimate business expenses on the hotel transaction (the hotel expenses and the dinner expense). Because the reimbursement method is IBCP w/offsets, the card vendor will also be the payee for the personal expenses on the hotel transaction up to the total amount of out-of-pocket cash expense submitted on this expense report. Since the non-reimbursable in-room movie expense (USD 14) is less than the total out-of-pocket cash expenses (USD 35) owed to the employee, the company will pay the USD 14 personal expense to the card vendor and offset that amount against the USD 35 owed to the employee. Thus the employee will only receive USD 21 of the USD 35 taxi expense. In this case there were enough out-of-pocket cash expenses to offset the non-reimbursable expenses so there is a net due to the employee for this expense report.

[61] entry_id [64] Entry Transaction Date [70] Vendor Name [63] Expense Type [68] Is Personal [62] Entry Transaction Type [163] Payer Payment Type [165] Payee Payment Type [169] Journal Amount [168] Debit Credit [167] Account Code [177] Cash Advance Amount [185] Cash Advance Transaction Type
89 7/15/2019 MARRIOTT Hotel N CHD COMPANY IBCP CORP USD 125 DR 99999 - -
90 7/16/2019 MARRIOTT Hotel N CHD COMPANY IBCP CORP USD 125 DR 99999 - -
91 7/15/2019 MARRIOTT Dinner N CHD COMPANY IBCP CORP USD 20 DR 600 - -
93 7/16/2019 Taxi Local Trans N REG COMPANY EMPLOYEE USD 21 DR 88888 - -
93 7/16/2019 Taxi Local Trans N REG COMPANY IBCP CORP USD 14 DR 88888 - -

IBCP With Personal Expense Where Out-of-Pocket Is Less Than Personal Expense

The Payer for both transactions is the company. The Payee is the corporate card vendor for the legitimate business expenses on the Hotel transaction (the Hotel expenses and the Dinner expense). Because the reimbursement method is IBCP w/offsets, the card vendor will also be the payee for the personal expenses on the Hotel transaction up to the total amount of out-of-pocket cash expense submitted on this expense report. Since the non-reimbursable in-room movie expense (USD 14) is greater than the total out-of-pocket cash expenses (USD 5) owed to the employee, the company will pay only USD 5 of the USD 14 personal expense to the card vendor and offset that amount against the USD 5 owed to the employee. Thus the employee will not receive any reimbursement and will personally owe the card vendor for the difference between the USD 5 paid by the company on his behalf and the USD 14 charge, or USD 9. In this case there were not enough out-of-pocket cash expenses to offset the non-reimbursable expenses so the employee is responsible to make up the difference with the card vendor.

[61] entry_id [64] Entry Transaction Date [70] Vendor Name [63] Expense Type [68] Is Personal [62] Entry Transaction Type [163] Payer Payment Type [165] Payee Payment Type [169] Journal Amount [168] Debit Credit [167] Account Code [177] Cash Advance Amount [185] Cash Advance Transaction Type
95 7/15/2019 MARRIOTT Hotel N CHD COMPANY IBCP CORP USD 125 DR 99999 - -
98 7/16/2019 MARRIOTT Hotel N CHD COMPANY IBCP CORP USD 125 DR 99999 - -
96 7/16/2019 MARRIOTT Dinner N CHD COMPANY IBCP CORP USD 20 DR 600 - -
99 7/16/2019 PARKING Parking N REG COMPANY IBCP CORP USD 5 DR 40 - -

CBCP Corporate Card Charge for Entirely Personal Expense (Net Due Company With Consolidated or Verbose Extract)

The extract produces two records for this single transaction. One record addresses payment that must be made to the card vendor by the company. The Payer is the company. The Payee is the corporate card vendor. The amount is a debit of USD 49 to the clearing account. Since there are no employee out-of-pocket expenses on this expense report there is nothing to offset the amount that the employee owes the company. Therefore, a separate record is created to address the net due company condition. In this record the Payer is the employee and the Payee is the company. The amount is a credit of USD 49 to the clearing account. The company’s financial system must have a process for dealing with this employee receivable condition. The CT&E system will not “carry over” this net due company amount to subsequent expense reports.

The company will pay the credit card vendor for the full amount due the card and retain a corresponding employee receivable (most likely represented as a debit in the employee’s vendor account. This allows natural offsetting to occur if there are subsequent amounts due the employee posted to their vendor record in the future.

[61] entry_id [64] Entry Transaction Date [70] Vendor Name [63] Expense Type [68] Is Personal [62] Entry Transaction Type [163] Payer Payment Type [165] Payee Payment Type [169] Journal Amount [168] Debit Credit [167] Account Code [177] Cash Advance Amount [185] Cash Advance Transaction Type
- 6/1/2016 - Dues Y REG EMPLOYEE COMPANY USD -49 CR cbcp180 - -
- 6/1/2016 - Dues Y REG COMPANY CBCP CORP USD 49 DR cbcp180 - -
- 6/1/2016 - Tolls Y REG EMPLOYEE COMPANY USD -32 CR compaid374 - -
- 6/1/2016 - Tolls Y REG COMPANY CBCP CORP USD 32 DR compaid374 - -

CBCP Corporate Card Charge with Itemization and Personal Expense (Net Due Employee With Consolidation)

The Payer for both transactions is the company. The Payee is the corporate card vendor for the full amount of the hotel transaction (the company owes the card vendor for the entire amount of the transaction, including the non-reimbursable in-room movie) and the employee for the balance of the taxi expense after the offset is taken for the in-room movie portion of the corporate card transaction. The employee would normally be reimbursed for the full USD 35 out-of-pocket taxi expense but, because a portion of the company paid corporate card transaction was not a legitimate business expense, the system reduces the amount due to the employee by the amount of the non-reimbursable expense. In this case there was enough out-of-pocket cash expenses to offset the non-reimbursable expenses so there is a net due to the employee for this expense report.

[61] entry_id [64] Entry Transaction Date [70] Vendor Name [63] Expense Type [68] Is Personal [62] Entry Transaction Type [163] Payer Payment Type [165] Payee Payment Type [169] Journal Amount [168] Debit Credit [167] Account Code [177] Cash Advance Amount [185] Cash Advance Transaction Type
4252 6/4/2019 MARRIOTT Hotel N CHD COMPANY CBCP CORP USD 125 DR 474230 - -
4253 6/3/2019 MARRIOTT Hotel N CHD COMPANY CBCP CORP USD 125 DR 7271001 - -
4254 6/3/2019 MARRIOTT Dinner N CHD COMPANY CBCP CORP USD 20 DR 474230 - -
4291 5/29/2019 Taxi Local Trans N REG COMPANY EMPLOYEE USD 35 DR 474230 - -
4255 6/5/2019 MARRIOTT In-room movie Y REG COMPANY CBCP CORP USD 14 DR 199999 - -

CBCP Corporate Card Charge for Entirely Personal Expense (Net Due Company With Verbose Extract)

The extract produces two records for this single transaction. One record addresses payment that must be made to the card vendor by the company. The Payer is the company. The Payee is the corporate card vendor. The amount is a debit of USD 300 to the clearing account. The second record is created to address the net due company condition. In this record the Payer is the employee and the Payee is the company. The amount is a credit of USD 300 to the clearing account. The company’s financial system must have a process for dealing with this employee receivable condition. The CT&E system will not “carry over” this net due company amount to subsequent expense reports.

[61] entry_id [64] Entry Transaction Date [70] Vendor Name [63] Expense Type [68] Is Personal [62] Entry Transaction Type [163] Payer Payment Type [165] Payee Payment Type [169] Journal Amount [168] Debit Credit [167] Account Code [177] Cash Advance Amount [185] Cash Advance Transaction Type
- 9/1/2016 Cheesecake Factory Dinner Y REG EMPLOYEE COMPANY USD -300 CR - - -
- 9/1/2016 Cheesecake Factory Dinner Y REG COMPANY CBCP CORP USD 300 DR - - -

CBCP Corporate Card Charge with Itemization and Personal Expense (Net Due Employee With No Offsets)

The records are slightly different from the previous example where offsets are built into the extract. In this case, where there are no built-in offsets, each record is distinct and the offset will need to be calculated in the client’s bridge program. The Payer for both transactions is the company except for the personal portion of the Hotel expense. The personal amount of USD 14 is represented with two distinct records. One record addresses the amount due to the corporate card vendor to ensure that the full amount of the otel transaction (including the personal amount) is paid to the card vendor. A second offsetting record addresses the same personal amount that the employee owes back to the company. In the first record, the company is the Payer and the Payee is the corporate card vendor for the USD 14 non-reimbursable in-room movie). In the second record the employee is the Payer and the Payee is the company for the credit amount of the USD 14 non-reimbursable in-room movie. The full USD 35 out-of-pocket taxi expense is handled as a normal out-of-pocket cash expense with the company being the Payer and the employee being the Payee. The client’s bridge program will need to summarize the two records (+USD 35 taxi and -USD 14 in-room movie) to arrive at the USD 21 due to the employee.

[61] entry_id [64] Entry Transaction Date [70] Vendor Name [63] Expense Type [68] Is Personal [62] Entry Transaction Type [163] Payer Payment Type [165] Payee Payment Type [169] Journal Amount [168] Debit Credit [167] Account Code [177] Cash Advance Amount [185] Cash Advance Transaction Type
4336 6/6/2019 MARRIOTT Hotel N CHD COMPANY CBCP CORP USD 125 DR 474230 - -
4337 6/7/2019 MARRIOTT Hotel N CHD COMPANY CBCP CORP USD 125 DR 474230 - -
4338 6/8/2019 MARRIOTT Dinner N CHD COMPANY CBCP CORP USD 20 DR 474230 - -
4339 6/8/2019 MARRIOTT In-Room Movie Y CHD COMPANY CBCP CORP USD 14 DR 199999 - -
4339 6/8/2019 MARRIOTT In-Room Movie Y CHD EMPLOYEE COMPANY USD 14 CR 199999 - -
4340 6/8/2019 Taxi Local Trans N REG COMPANY EMPLOYEE USD 35 DR 474230 - -

Schemas

Expense

Expense - Employee

Name Type Format Description
employeeCustom1Code through employeeCustom21Code CustomField - The details from the custom fields. These fields may not have data, depending on the configuration. Maximum length 48 characters.
employeeCustom1Value through employeeCustom21Value CustomField - The details from the custom fields. These fields may not have data, depending on the configuration. If configured as a list, this field contains the name of the list item. Maximum length 64 characters.
employeeFirstName String - Alphanumeric. First name of employee. Maximum length 32 characters.
employeeId String - Alphanumeric. Employee ID often also serves as the employee’s Vendor ID for AP system integrations or payroll ID for payroll integrations. Maximum length 128 characters.
employeeLastName String - Alphanumeric. Last name of employee. Maximum length 32 characters.
employeeMI String - Alphanumeric. Middle initial of employee. Maximum length 1 character.
employeeOrgUnit1Code through employeeOrgUnit6Code CustomField - The details from the custom fields. These fields may not have data, depending on the configuration. Maximum length 48 characters.
employeeOrgUnit1Value through employeeOrgUnit6Value CustomField - The details from the custom fields. These fields may not have data, depending on the configuration. If configured as a list, this field contains the name of the list item. Maximum length 64 characters.

Expense - Report

Name Type Format Description
cashAdvanceReturnsAmount Number Maximum 23 digits to the left of the decimal; maximum 8 digits to the right of the decimal; with a maximum of 23 digits for the entire field. Currency. Amount of cash advance returned.
employeeCurrencyAlphaCode String 3-letter ISO 4217 alpha code. Alphanumeric. Reimbursement currency.
homeCountryCode String ISO 3166-1 alpha-2 country code. Alphanumeric. The report country. Example: United States is US.
isTest String Y/N Signifies if this report belongs to a test user in system. Y = test user, N = not a test user.
ledgerCode String - Alphanumeric. External accounting system ID. Maximum length 20 characters.
payrollPayIndicator String Y/N This field indicates whether the expense group the report user belongs to is configured to reimburse employees using Payroll.
payrollPaymentClearingAccountCode String - Alphanumeric. SAP customers who reimburse their employees via Payroll need to capture a payroll clearing account code as part of the accounting entry during the financial posting process. Maximum length 128 characters.
reportCreationDate String yyyy-mm-ddThr:min:sec.msZ Date the report was created. Maximum length 24 characters.
reportCustom1Code through reportCustom20Code CustomField - The details from the custom fields. These fields may not have data, depending on the configuration. Maximum length 48 characters.
reportCustom1Value through reportCustom20Value CustomField - The details from the custom fields. These fields may not have data, depending on the configuration. If configured as a list, this field contains the name of the list item. Maximum length 64 characters.
reportEndDate String yyyy-mm-ddThr:min:sec.msZ End date from the report header. Can be imported from trip data or manually entered.
reportId String Unique (across all SAP Concur clients) 32 character alphanumeric. Alphanumeric. Often used as a voucher number when integrating across AP systems.
reportKey Number - A unique ID (within a single SAP Concur client's company) generated by the system. An alternative to the reportId. Starts with 1 and increments with each expense report. Maximum length 11 characters.
reportName String - Alphanumeric. Report name assigned by employee. Maximum length 40 characters.
reportOrgUnit1Code through reportOrgUnit20Code CustomField - The details from the custom fields. These fields may not have data, depending on the configuration. The second segment in the fully qualified GL string should use Org Unit 2, except the natural account field. The natural account data is stored in column 167 of the SAE. Maximum length 48 characters.
reportOrgUnit1Value through reportOrgUnit20Value CustomField - The details from the custom fields. These fields may not have data, depending on the configuration. If configured as a list, this field contains the name of the list item. Maximum length 64 characters.
reportPaymentProcessingDate String yyyy-mm-ddThr:min:sec.msZ The date that the report completed all approvals and was ready to be extracted for payment. Maximum length 24 characters.
reportStartDate String - Report start date. Maximum length 24 characters.
reportSubmitDate String - Date/time the employee submitted the report for approval. Maximum length 24 characters.
reportUserDefinedDate String - Custom date/time specified by user. Maximum length 24 characters.
revisionNumber Number - Report revision number. This will be used to track changes made to posted expenses. Default value is 1. Maximum length 32 characters.
totalApprovedAmount Number Maximum 23 digits to the left of the decimal; maximum 8 digits to the right of the decimal; with a maximum of 23 digits for the entire field. Total approved amount of the report.
versionId Number - The version of the FI Document, which is the same as the version of the API endpoint. Maximum length 32 characters.

Expense - expenseEntry

Name Type Format Description
cardAccountID String - Alphanumeric. ID for the card account. This can be used by the receiving system to condense transactions associated with this card. Maximum length 32 characters.
cardProgramTypeCode String - Alphanumeric. The code used to identify the card’s program type. Maximum length 5 characters.
cardStatementPeriodEndDate String yyyy-mm-ddThr:min:sec.msZ The date of the end of the statement period. Maximum length 24 characters.
cardStatementPeriodStartDate String yyyy-mm-ddThr:min:sec.msZ The date of the start of the statement period. Maximum length 24 characters.
cardTransactionAmount Number Maximum 23 digits to the left of the decimal; maximum 8 digits to the right of the decimal; with a maximum of 23 digits for the entire field. Currency. Amount of the charge in the spend currency.
cardTransactionCurrency String ISO 4217 3-letter alpha code. Alphanumeric. Currency code for the spend currency.
cardTransactionID String - Reference number from the credit card vendor. Maximum length 32 characters.
cardTransactionPostedAmount Number Maximum 23 digits to the left of the decimal; maximum 8 digits to the right of the decimal; with a maximum of 23 digits for the entire field. Amount of the charge in the billing currency of the card.
cardTransactionPostedCurrency String ISO 4217 3-letter alpha code. Alphanumeric. Currency code for the card billing currency.
clearingAccountCode String - Alphanumeric. Contains the expense type account code. - or - If a CBCP Personal expense, the company card clearing account code. - or - If charge is tied to a Statement Report, and accounting code is set for Company Billed card account, the card's accounting code as specified in the Account Code field when creating or editing a CBS account. Maximum length 20 characters.
entryApprovedAmount Number Maximum 23 digits to the left of the decimal; maximum 8 digits to the right of the decimal; with a maximum of 23 digits for the entire field. Currency. Amount approved in the reimbursement currency.
entryCountryCode String 2-character country code. Alphanumeric. Report entry country code.
entryCountrySubCode String - Alphanumeric. Report entry country sub code. Maximum length 6 characters.
entryCurrAlphaCode String ISO 4217 3-letter alpha code. Alphanumeric. Currency ISO alpha code for the spend currency if not an imported credit card or the invoice currency if this is a credit card. Maximum length 4 characters.
entryCustom1Code through entryCustom40Code CustomField - The details from the custom fields. These fields may not have data, depending on the configuration. Maximum length 48 characters.
entryCustom1Value through entryCustom40Value CustomField - The details from the custom fields. These fields may not have data, depending on the configuration. If configured as a list, this field contains the name of the list item. Maximum length 64 characters.
entryDate String yyyy-mm-ddThr:min:sec.msZ Date that this expense was incurred (when the money was spent or credit card receipt date).
entryDescription String - Alphanumeric. Expense description as entered by the employee. Maximum length 64 characters.
entryElectronicReceiptId String - GUUID. Electronic receipt ID. Maximum length 24 characters.
entryExchangeRate Number - Rate used to convert from the report entry (spend) currency to the report (reimbursement) currency. Maximum length 23 characters.
entryExchangeRateDirection String M/D Alphanumeric. The direction of the exchange rate conversion. Either: M = Multiply or D = Divide.
entryId String - Report entry sync GUUID unique key. Maximum length 32 characters.
entryIsBillable String Y/N Yes or no is the expense billable.
entryIsPersonal String Y/N Yes or no is the expense personal.
entryLocationCityName String - Alphanumeric. Report entry location city name. Maximum length 64 characters.
entryLocationName String - Alphanumeric. Report entry location name. Maximum length 64 characters.
entryOrgUnit1Value through entryOrgUnit6Value CustomField - The details from the custom fields. These fields may not have data, depending on the configuration. If configured as a list, this field contains the name of the list item. Maximum length 64 characters.
entryOrgUnit1Code through entryOrgUnit6Code CustomField - The details from the custom fields. These fields may not have data, depending on the configuration. Maximum length 48 characters.
entryReceiptId String - GUUID. Non-electronic receipt image. Maximum length 32 characters.
entryReceiptType String T/R/N Alphanumeric. One of these: T = Tax receipt, R = Regular receipt, or N = No receipt.
entrySupplierTaxID String - Alphanumeric. Report entry XML receipt supplier tax ID. Maximum length 64 characters.
entryUuid String - Report Entry XML Receipt UUID. Maximum length 32 characters.
entryVendorCode String - Alphanumeric. Vendor name list short code. Maximum length 32 characters.
entryVendorDescription String - Alphanumeric. Vendor description. Maximum length 64 characters.
expensePayIndicator String Either: 1 = Expense Pay or blank = not Expense Pay. Indicates whether Expense Pay reimbursed this journal entry.
expenseTypeCode String - Alphanumeric. Code for the expense type. Maximum length 5 characters.
expenseTypeName String - Alphanumeric. Expense type name. Maximum length 64 characters.
legacyEntryId Number - Legacy report entry key. Maximum length 11 characters.
liabilityAccountCode String - Alphanumeric. The liability account code assigned to the funding account paying this entry. Maximum length 48 characters.
offsetPayType String Y/N Use Offsets. Y = Yes, N= No.
reportEntryPatKey String - Alphanumeric. Report Entry Payment Code. Maximum length 4 characters.

Expense - Allocation

Name Type Format Description
allocationCustom1Code through allocationCustom20Code CustomField - The details from the custom fields. These fields may not have data, depending on the configuration. Maximum length 48 characters.
allocationCustom1Value through allocationCustom20Value CustomField - The details from the custom fields. These fields may not have data, depending on the configuration. If configured as a list, this field contains the name of the list item. Maximum length 64 characters.
allocationId String - GUUID. System-generated unique key for this allocation record. Maximuml length 32 characters.
allocationPercentage Number - Percent of the report entry assigned to this allocation record. Maximum length 11 characters.

Expense - Journal

Name Type Format (length) Description
accountingTransactionType String - Alphanumeric. This is the Intuit QuickBooks specific transaction value. It will be null or a value (GJ, CC, or BILL) depending on if it’s a journalpayee or journalpayer. This determines if a transaction should be posted as Bill or Credit Card in QuickBooks. Maximum length 24 characters.
amountGrossCard Number Maximum 23 digits to the left of the decimal; maximum 8 digits to the right of the decimal; with a maximum of 23 digits for the entire field. Amount due to the company card of either CBCP or IBCP type for this detail row.
amountNetOfReclaim Number Maximum 23 digits to the left of the decimal; maximum 8 digits to the right of the decimal; with a maximum of 23 digits for the entire field. Currency. Gross Journal amount subtracting reclaimable tax. Or the Net Journal amount adding non-reclaimable tax.
amountNetOfTax Number Maximum 23 digits to the left of the decimal; maximum 8 digits to the right of the decimal; with a maximum of 23 digits for the entire field. Currency. Allocated net of reclaim tax. You get this by starting from the net and adding the tax that is not reclaimable, or starting with the gross and subtracting reclaimable.
amountTax Number Maximum 23 digits to the left of the decimal; maximum 8 digits to the right of the decimal; with a maximum of 23 digits for the entire field. Currency. This is the Gross Journal amount subtracting the total Tax amount.
cardTransactionReferenceNumber Number - Reference number from the credit card vendor. Maximum length 64 characters.
journalAccountCode String - Alphanumeric. Contains the expense type account code. - or - If a CBCP Personal expense, the company card clearing account code. - or - If charge is tied to a Statement Report, and accounting code is set for Company Billed card account, the card's accounting code as specified in the Account Code field when creating or editing a CBS account. Maximum length 48 characters.
journalPayee String - Alphanumeric. Payment code name for the payee. Maximum length 4 characters.
journalPayer String - Alphanumeric. Payment code name for the payer. Maximum length 4 characters.
taxGuid String - GUUID. Unique identifier associated with the report entry tax allocation. Maximum length 32 characters.

Expense - cashAdvanceApplication

Name Type Format Description
cashAdvanceApplicationAmount Number Maximum 23 digits to the left of the decimal; maximum 8 digits to the right of the decimal; with a maximum of 23 digits for the entire field. Currency. Cash advance utilized amount.
cashAdvanceClearingAccountCode String - Alphanumeric. The Account Code is the clearing account code which was configured for the employee in the profile. Maximum length 48 characters.
cashAdvanceId String - GUUID. Unique system ID assigned to the cash advance. Maximum length 32 characters.
cashAdvanceTransactionType Number - Type of transaction: 1 = Issue or return to administrator, 2 = Application, including cash advance return expense within a report, or 3 = System cash advance, from balance carry forward.

Schemas - Invoice

Invoice - requestHeader

Name Type Format Description
amountNetInvoice Number - The invoice total amount minus the shipping and tax amounts. Maximum length 23 characters.
amountShippingTotal Number - The value for the shipping amount header field. Maximum length 23 characters.
amountTax Number - The total amount of tax on a given invoice. Maximum length 23 characters.
amountVAT1 through amountVAT4 Number 23 The individual total VAT amounts for the invoice. Maximum length 23 characters.
clearingAccountCode String - Contains the expense type account code. - or - If a CBCP Personal expense, the company card clearing account code. - or - If charge is tied to a Statement Report, and accounting code is set for Company Billed card account, the card's accounting code as specified in the Account Code field when creating or editing a CBS account. Maximum length 20 characters.
currencyAlphaCode String ISO 4217 3-letter alpha code. Currency ISO alpha code for the spend currency if not an imported credit card or the invoice currency if this is a credit card.
deliverySlipNumber String - Delivery slip number of the receipt which is associated to the invoice line item. Maximum length 256 characters.
discountPercentage Number Percentage Percent value that defines the amount of discount that would be applied.
discountTermsDays Number - Numeric value defining the discount term day amount. Maximum length 3 characters.
invoiceDate String YYYY-MM-DD Date of the invoice.
invoicePayIndicator String Y/N- Signifies if this report belongs to a test user in system.
invoiceReceivedDate String YYYY-MM-DD The date on which the invoice was received.
isTest String Y/N Signifies if this report belongs to a test user in system.
ledgerCode String - External accounting system ID. Maximum length 20 characters.
ledgerName String - The general ledger tied to the invoice. Maximum length 100 characters.
multiplePurchaseOrder String Y/N Defines whether or not multiple purchase orders are tied to the invoice.
netPaymentTermDays Number - Numeric value defining the payment term day amount. Maximum length 3 characters.
paymentDueDate String YYYY-MM-DD The date the payment is due for a given invoice.
payMethodType String Drop Down Selector. Valid format options include: ACH, client paid, check, PAYPVD, wire, card, or VCHER. The method used to pay the invoice, as of the point in time the extract is run. NOTE: It is possible for the method to be changed or updated post-extract through either the Payment Confirmation import (if the client controls payments), or through Invoice Pay (using Payment Manager).
postingDate String YYYY-MM-DD The date the invoice will be posted to the ERP system.
processCompleteDate String YYYY-MM-DD The date the invoice was processed.
reqKey Number Integer An integer that uniquely defines this invoice in SAP Concur. This is the value that the Invoice Confirmation Import uses to match to this particular invoice.
requestCreationDate String YYYY-MM-DD The date the invoice was originally saved.
requestCustom1Code through requestCustom24Code CustomField The details from the custom fields. These fields may not have data, depending on the configuration. Maximum length 48 characters.
requestCustom1Value through requestCustom24Value CustomField - The details from the custom fields. These fields may not have data, depending on the configuration. Maximum length 48 characters.
requestDescription String - The invoice’s description. Maximum length 250 characters.
requestId String - The unique identification assigned to the invoice. Maximum length 20 characters.
requestOrgUnit1Code through requestOrgUnit6Code CustomField - The details from the custom fields. These fields may not have data, depending on the configuration. Maximum length 48 characters.
requestOrgUnit1Value through requestOrgUnit6Value CustomField - The details from the custom fields. These fields may not have data, depending on the configuration. Maximum length 48 characters.
requestTitle String - The invoice name. Maximum length 100 characters.
requestTotal Number Maximum 23 digits to the left of the decimal; maximum 8 digits to the right of the decimal; with a maximum of 23 digits for the entire field. The sum of all Line Item Amounts plus Shipping Amount and Tax Amount for the invoice.
revisionNumber Number - Invoice revision number. Default value is 1. Maximum length 32 characters.
submitDate String YYYY-MM-DD Date/time the employee submitted the invoice for approval.
vendorInvoiceNumber String - The invoice number assigned by the vendor. Maximum length 50 characters.
versionId String - The version of the FI Document, which is the same as the version of the API endpoint. Maximum length 32 characters.

Invoice - ownerEmployee

Name Type Format Description
employeeCustom1Code through employeeCustom21Code CustomField - The details from the custom fields. These fields may not have data, depending on the configuration. Maximum length 48 characters.
employeeCustom1Value through employleeCustom21Value CustomField - The details from the custom fields. These fields may not have data, depending on the configuration. Maximum length 48 characters.
employeeFirstName String - First name of employee. Maximum length 32 characters.
employeeId String - Employee ID often also serves as the employee’s Vendor ID for AP system integrations or Payroll ID for Payroll integrations. Maximum length 48 characters.
employeeLastName String - Last name of employee. Maximum length 32 characters.
employeeMI String - Middle initial of employee. Maximum length 1 character.
employeeOrgUnit1Value through employeeOrgUnit6Value CustomField - The details from the custom fields. These fields may not have data, depending on the configuration. Maximum length 48 characters.

Invoice - Vendor

Name Type Format Description
vendorCode String - The financial system's code for this vendor. Maximum length 23 characters.
vendorContactFirstName String - Buyer contact for the vendor record’s first name. Maximum length 255 characters.
vendorContactLastName String - Buyer contact for the vendor record’s last name. Maximum length 255 characters.
vendorName String - The financial system's name for this vendor. Maximum length 255 characters.
vendorRemitToAddressCode String Less than or equal to 64. The financial system's code for this address.

Invoice - lineItem

Name Type Format Description
allocationAccountCode String - The Account Code for the Allocation related to this Journal Entry. Maximum length 20 characters.
allocationCustom1Code through allocationCustom20Code CustomField - The details from the custom fields. These fields may not have data, depending on the configuration. Maximum length 48 characters.
allocationCustom1Value through allocationCustom20Value CustomField - The details from the custom fields. These fields may not have data, depending on the configuration. Maximum length 48 characters.
allocationKey Number - System-generated unique key for this allocation record. Maximum length 13 characters.
allocationPercentage Number - Percent of the report entry assigned to this allocation record. Maximum length 64 characters.
journal String - Container for journal entries tied to the allocation. Maximum length 48 characters.
accountCode Number - The financial system accounting code value tied to the invoice line. Maximum length 20 characters.
amountGross Number - The gross amount (total amount) of the invoice line item. Maximum length 23 characters.
amountNet Number - The net amount of the invoice line item not including shipping and tax. Maximum length 23 characters.
amountShipping Number Maximum 23 digits to the left of the decimal; maximum 8 digits to the right of the decimal; with a maximum of 23 digits for the entire field. The value for the Shipping Amount header field. Maximum 23 digits to the left of the decimal; maximum 8 digits to the right of the decimal; with a maximum of 23 digits for the entire field.
expenseTypeCode String - Code for the expense type so a value that isn’t language dependent is returned. Maximum length is 7 characters.
expenseTypeName String - Expense type name. Maximum length 64 characters.
externalLineItemId String - The PO Line item associated with to the Invoice. Maximum length 100 characters.
lineItemCode String - The Primary Key value for the expense type. Maximum length 7 characters.
lineItemCustom1Code through lineItemCustom20Code CustomField - The details from the custom fields. These fields may not have data, depending on the configuration. Maximum length 48 characters.
lineItemCustom1Value through lineItemCustom20Value CustomField - The details from the custom fields. These fields may not have data, depending on the configuration. Maximum length 48 characters.
lineItemDeliverySlipNumber String - Delivery Slip Number of the receipt which is associated to the invoice line item. Maximum length 256 characters.
lineItemDescription String - The description of the goods or services being purchased on the individual invoice line. Maximum length 255 characters.
lineItemPurchaseOrderNumber String - The purchase order number associated with the invoice line item (for a multiple purchase order-based invoice), or the purchase order number associated with the header (for a single purchase order-based invoice). Maximum length 10 characters.
lineItemQuantity String - The quantity of the line item. Maximum length 23 characters.
lineItemSequenceOrder Number Integer Line item number for the line item related to this Journal Entry. Value is dynamically generated by the system based on the number of lines.
lineItemUnitPrice Number - The quantity unit price for the item being purchased. Maximum length 23 characters.
poLineNumber Number - The PO line item number associated to the payment request. Maximum length 48 characters.
receiptNumber Number - The Goods Receipt number. Maximum length 256 characters.
receiptQuantity Number - The Goods Received quantity. Maximum length 23 characters.
receiptItemID Number - The ID of the Goods Receipt tied to the Invoice and PO Line. Maximum length 48 characters.

Invoice - Tax

Name Type Format Description
amountTax Number - The taxation amount that exists on the invoice line. Maximum length 23 characters.
taxCode String - Tax code assigned to this tax authority for the expense type entered on the expense entry. Maximum length 20 characters.
taxField String - Defines which database field the tax resides in. Maximum length 20 characters.

Cash Advance

Cash Advance - employeeData

Name Type Format Description
employeeCustom1Code through employeeCustom21Code CustomField - The details from the custom fields. These fields may not have data, depending on the configuration. Maximum length 48 characters.
employeeCustom1Value through employeeCustom21Value CustomField - The details from the custom fields. These fields may not have data, depending on the configuration. Maximum length 64 characters.
employeeFirstName String - Alphanumeric. First name of employee. Maximum length 32 characters.
employeeId String - Alphanumeric. Employee ID often also serves as the employee’s Vendor ID for AP system integrations or Payroll ID for Payroll integrations. Maximum length 128 characters.
employeeLastName String - Alphanumeric. Last name of employee. Maximum length 32 characters.
employeeMI String - Alphanumeric. Middle initial of employee. Maximum length 1 character.
employeeOrgUnit1Code through employeeOrgUnit6Code CustomField - The details from the custom fields. These fields may not have data, depending on the configuration. Maximum length 48 characters.
employeeOrgUnit1Value through employeeOrgUnit6Value CustomField - The details from the custom fields. These fields may not have data, depending on the configuration. Maximum length 64 characters.

Cash Advance - cashAdvanceData

Name Type Format Description
cardAccountID String - Alphanumeric. ID will be used initially by the receiving system to “condense” transactions associated with this card. It will also be used to retrieve the card number in a separate API call. Maximum length 32 bytes.
cardTransactionAmount Number Maximum 23 digits to the left of the decimal; maximum 8 digits to the right of the decimal; with a maximum of 23 digits for the entire field. Currency. Amount of the charge in the spend currency.
cardTransactionCurrency String ISO 4217 3-letter alpha code. Alphanumeric. Currency code for the spend currency.
cardTransactionID String - Alphanumeric. Calculated value assigned to this card entry during the import process. Maximum length 32 characters.
cardTransactionPostedAmount Number Maximum 23 digits to the left of the decimal; maximum 8 digits to the right of the decimal; with a maximum of 23 digits for the entire field. Currency. Amount of the charge in the billing currency of the card.
cardTransactionPostedCurrency String ISO 4217 3-letter alpha code. Alphanumeric. Currency code for the card billing currency.
cashAdvanceId String - GUUID. Unique system ID assigned to the cash advance. Maximum length 32 characters.
clearingAccountCode String - Alphanumeric. Contains the expense type account code. - or - If a CBCP Personal expense, the company card clearing account code. - or - If charge is tied to a Statement Report, and accounting code is set for Company Billed card account, the card's accounting code as specified in the Account Code field when creating or editing a CBS account. Maximum length 20 characters.
countryCode String ISO 3166-1 alpha-2 country code. Alphanumeric. The report country. Example: United States is US.
countrySubCode String - Alphanumeric. Report entry country sub code. Maximum length 6 characters.
currencyAlphaCode String ISO 4217 3-letter alpha code. Alphanumeric. Currency ISO alpha code for the spend currency if not an imported credit card or the invoice currency if this is a credit card.
currencyNumCode String ISO 4217 3-letter alpha code. Alphanumeric. Currency code for the transaction currency using ISO number code.
employeeCurrencyAlphaCode String ISO 4217 3-letter alpha code. Alphanumeric. Reimbursement currency.
exchangeRate Number - Rate used to convert from the report entry (spend) currency to the report (reimbursement) currency. Maximum length 23 characters.
expensePayIndicator String Y/N Indicates whether Expense Pay reimbursed this journal entry. Either: Y = Expense Pay or N = not Expense Pay.
issuedDate String yyyy-mm-ddThr:min:sec.msZ Date of issue.
isTest String Y/N Signifies if this report belongs to a test user in system.
entrylocationName String - Alphanumeric. The report entry location name (for example, city name). Maximum length 64 characters.
name String - Alphanumeric. Cash advance request name. Maximum length 40 characters.
paymentMethod String 0 = Non-Expense Pay method used for disbursement or 1 = Expense Pay method used for disbursement. Alphanumeric. The method used, either Expense Pay or Other, used for disbursement of the cash advance.
purpose String - Alphanumeric. Describes the purpose of cash advance issued. Maximum length 2,000 characters.
requestAmount Number Maximum 23 digits to the left of the decimal; maximum 8 digits to the right of the decimal; with a maximum of 23 digits for the entire field. Currency. For issue journal record, the total amount of the cash advance in the cash advance transaction currency.
requestDate String yyyy-mm-ddThr:min:sec.msZ Date of cash advance request from the detailed cash advance record.
requestedDisbursementDate String yyyy-mm-ddThr:min:sec.msZ Cash advance disbursement date.
transactionType String 1 = Issue or Return to Administrator, 2 = Application, including Cash Advance Return expense within a report, or 3 = System Cash advance, from balance carry forward. Alphanumeric. Type of transaction.
travelEndDate String yyyy-mm-ddThr:min:sec.msZ The last day of the trip on the assigned travel request itinerary.
travelStartDate String yyyy-mm-ddThr:min:sec.msZ The first day of the trip on the assigned travel request itinerary.

Cash Advance - journalData

Name Type Format Description
accountCode String - Alphanumeric. Contains the expense type account code. - or - If a CBCP Personal expense, the company card clearing account code. - or - If charge is tied to a Statement Report, and accounting code is set for Company Billed card account, the card's accounting code as specified in the Account Code field when creating or editing a CBS account. Maximum length 48 characters.
amount Number Maximum 23 digits to the left of the decimal; maximum 8 digits to the right of the decimal; with a maximum of 23 digits for the entire field. Currency. Value, as credit or debit, of the amount to be exchanged between the payer and payee for this expense account code (not an absolute value) EXAMPLES: Value of zero, credit, or debit, as the following: 0 (Zero) "0," + (Plus / Debit) "+50.00," or - (Minus / Credit) "-50.00."
debitOrCredit String DR/CR Alphanumeric. Either: DR = Debit or CR = credit.
payee String - Alphanumeric. Either a company or an employee depending on the payment type. Maximum length 64 characters.
payer String - Alphanumeric. Either a company or an employee depending on the payment type. Maximum length 64 characters.
paymentCode String - Alphanumeric. The payment code for either a payee or payer. Maximum length 80 characters.

Insights

Latest Bookings

Gets the latest hotel and air booking for a particular user.

Version

3.0

Retrieve the latest hotel and air booking for a particular user

GET /api/v3.0/insights/latestbookings/

Parameters

Name Type Format Description
user string query The login ID of the user. The user must have the Web Services Admin (Professional) or Can Administer (Standard) user role to use this parameter.

Latest Bookings - Schema

Latest Booking

Name Type Format Description
Airlines array Airline The latest booked airline segments.
Hotel Hotel - The latest booked hotel segment.

Airline

Name Type Format Description
BookingClass string - The booking class of the latest booked airline segment.
Code string - The airline code of the latest booked airline segment.

Hotel

Name Type Format Description
Location string - The IATA airport code of the location of the latest booked hotel segment.
StarRating Int32 - The star rating of the latest booked hotel segment. Possible values are from 0 - 5. Values 1 - 5 are mapped to the Northstar standard. If the value is 0, the star rating could not be found.

Opportunities

Retrieves a collection of opportunities for a specified trip or for all trips that fall within a date range.

Version

3.0

GET https://www.concursolutions.com/api/v3.0/insights/opportunities

Parameters

Name Type Format Description
tripId string query The trip id
opportunityType string query Comma seperated list of opportunities (Hotel, Car, Air, Rail, Taxi and Service) to get. Do not specify any values to get all opportunities
fromUtc DateTime query The From date in UTC for the date range
toUtc DateTime query The To date in UTC for the date range

Opportunities - Schema

Opportunities

Name Type Format Description
Items Array Opportunity The result collection.
NextPage string - The URI of the next page of results, if any.

Opportunity

Name Type Format Description
EndCityCode string - The city code of the destination city where the opportunity is offered
EndDateLocal DateTime - The local end date of the location where the opportunity is offered
EndPostalCode string - The postal code of the destination location where the opportunity is offered
ID string - The unique identifier of the resource.
IsActive boolean - Indicates that the opportunity is currently active
StartCityCode string - The city code of the originating city where the opportunity is offered
StartDateLocal DateTime - The local start date of the location where the opportunity is offered
StartPostalCode string - The postal code of the originating location where the opportunity is offered
TripId string - The trip id of the associated itinerary
Type string - The type of opportunity. Possible values: 'Hotel', 'Car', 'Air', 'Rail', 'Taxi' or 'Service'
URI string - The URI to the resource.

Invoice

Retrieve Invoice Digests v3

Version

3.0

Retrieves All Invoice Digests Based On the Search Criteria

GET /api/v3.0/invoice/paymentrequestdigests

Parameters

Name Type Format Description
offset string query The start of the page offset.
limit Int32 query The number of records to return. Default: 1,000
approvalStatus string query A code representing an Invoice Approval Status. Use GET /invoice/localizeddata to get the available approval status codes.
paymentStatus string query A code representing an Invoice Payment Status. Use GET /invoice/localizeddata to get the available payment status codes
vendorInvoiceNumber string query Vendor invoice number tied to the invoice.
createDateBefore DateTime YYYY-MM-DD The invoice create date is before this date.
createDateAfter DateTime YYYY-MM-DD The invoice create date is after this date.
userDefinedDateBefore DateTime YYYY-MM-DD The invoice user defined date is before this date.
userDefinedDateAfter DateTime YYYY-MM-DD The invoice user defined date is after this date.
submitDateBefore DateTime YYYY-MM-DD The invoice submit date is before this date.
submitDateAfter DateTime YYYY-MM-DD The invoice submit date is after this date.
paidDateBefore DateTime YYYY-MM-DD The invoice paid date is before this date.
paidDateAfter DateTime YYYY-MM-DD The invoice paid date is after this date.
payMethodType string query Payment method type tied to an Invoice. Use GET /invoice/localizeddata to get the available Pay Method types.
lastModifiedDateBefore DateTime YYYY-MM-DD The invoice last modified date is before this date.
lastModifiedDateAfter DateTime YYYY-MM-DD The invoice last modified date is after this date.
extractedDateBefore DateTime YYYY-MM-DD The invoice extracted date is before this date.
extractedDateAfter DateTime YYYY-MM-DD The invoice extracted date is after this date.

Retrieves an Invoice Digest Based On ID

GET /api/v3.0/invoice/paymentrequestdigests/{id}

Parameters

Name Type Format Description
id string path Required The invoice ID

Retrieve Invoice Digests v3 - Schema

Payment Request Digests

Name Type Format Description
Items Array Payment Request Digest The result collection.
NextPage string - The URI of the next page of results, if any.
PaymentRequestDigest Array Payment Request Digest -
TotalCount Int32 - -

Payment Request Digest

Name Type Format Description
ApprovalStatusCode string - Required A code indicating the invoice's approval status.
CreateDate string - The date the invoice was created.
CurrencyCode string - The 3-letter ISO 4217 currency code for the invoice currency. Examples: USD - US dollars; BRL - Brazilian real; CAD - Canadian dollar; CHF - Swiss franc; EUR - Euro; GBO - Pound sterling; HKD - Hong Kong dollar; INR - Indian rupee; MXN - Mexican peso; NOK - Norwegian krone; SEK - Swedish krona.
ID string - The unique identifier of the resource.
InvoiceNumber string - The invoice number of the Invoice.
IsDeleted boolean - A true/false value which indicates whether the invoice has been deleted. (Deleted invoices are retained in the system for historical purposes.).
OwnerLoginID string - The login ID of the Invoice owner.
OwnerName string - The name of the Invoice owner.
PaidDate string - The date when all journal entries in the invoice were integrated with or extracted to the financial system.
PaymentRequestId string - Required The unique identifier of the Invoice summarized in this digest.
PaymentRequestUri string - Required URI of the Invoice summarized in this digest.
PaymentStatusCode string - Required A code indicating the invoice's payment status.
Total string - The total amount of the invoice.
URI string - The URI to the resource.
UserDefinedDate string - The invoice date as assigned by the user.
VendorName string - Required The name of the vendor.
PaymentMethod string - Payment method type tied to an Invoice.
LastModifiedDate string - The date the invoice was last modified.
ExtractedDate string - The date the invoice was extracted.

Invoice v3

Version

3.0

Retrieve an Invoice

GET /api/v3.0/invoice/paymentrequest/{id}

Parameters

Name Type Format Description
id string path Required Invoice ID.

Create a New Invoice

POST /api/v3.0/invoice/paymentrequest

Payload

Update an Invoice

PUT /api/v3.0/invoice/paymentrequest

Payload

Invoice v3 - Schema

Payment Request

Name Type Format Description
AmountWithoutVat string - The net amount of the invoice (excluding VAT).
BuyerCostCenter string - The company defined center responsible for the Invoice.
CheckNumber string - Check number of the payment made to the vendor.
CompanyBillToAddressCode string - The code which identifies the company location to which the vendor billed the invoice.
CompanyShipToAddressCode string - The code which identifies the company location to which the vendor shipped items listed in the invoice.
CountryCode string - Required The country code.
CurrencyCode string - The 3-letter ISO 4217 currency code for the invoice currency. Examples: USD - US dollars; BRL - Brazilian real; CAD - Canadian dollar; CHF - Swiss franc; EUR - Euro; GBO - Pound sterling; HKD - Hong Kong dollar; INR - Indian rupee; MXN - Mexican peso; NOK - Norwegian krone; SEK - Swedish krona.
Custom1 through Custom9 string - The details from the Custom fields. These may not have data, depending on configuration.
DataSource string - A code which indicates the method used to created the Invoice. Use GET /invoice/localizeddata to translate the code into text.
DeliverySlipNumber string - The delivery slip number associated with receiving receipt.
Description string - User entered description of the Invoice.
DiscountPercentage string - The discount from the supplier if the discount terms are met.
DiscountTerms string - The NET discount terms with a supplier when discounts apply.
EmployeeEmailAddress string - The email address of the employee to whom the invoice should be assigned. Not evaluated if EmployeeLoginId or EmployeeId match an employee. This value is required if none of the following are provided: LedgerCode; EmployeeLoginId, EmployeeId; PurchaseOrderNumber; ExternalPolicyId.
EmployeeId string - The company ID of the employee to whom the invoice should be assigned. Has precedence over EmployeeEmail; not evaluated if EmployeeLoginId matches an employee. This value is required if none of the following are provided: LedgerCode; EmployeeLoginId; EmployeeEmail; PurchaseOrderNumber; ExternalPolicyId.
EmployeeLoginId string - The login ID of the employee to whom the invoice should be assigned. Has precedence over EmployeeId and EmployeeEmail. This value is required if none of the following are provided: LedgerCode; EmployeeId; EmployeeEmail; PurchaseOrderNumber; ExternalPolicyId.
ExternalPolicyId string - The external policy ID of the Invoice. This value is required if none of the following are provided: LedgerCode; EmployeeLoginId, EmployeeId; EmployeeEmail; PurchaseOrderNumber.
InvoiceAmount string - Required User-entered value representing the total invoice amount, used to calculate amount remaining on the line item page.
InvoiceDate string - The date the vendor issued the Invoice.
InvoiceNumber string - The Invoice Number from the vendor for the Invoice.
InvoiceReceivedDate string - The date on which the invoice was received.
IsEmergencyCheckRun string - Is an emergency check run required (Y/N).
IsInvoiceConfirmed boolean - Indicates if the Invoice is confirmed or in a different status Supported values: true, false
LedgerCode string - A code which indicates which company journal the Invoice is assigned to. Use GET /invoice/localizeddata to obtain valid codes. This value is required if none of the following are provided: EmployeeLoginId; EmployeeId; EmployeeEmail; PurchaseOrderNumber; ExternalPolicyId.
LineItems array LineItem The details of the Core Payment Request Line Item Identity Fields.
Name string - Required The Invoice name.
NotesToVendor string - Information from the customer to the vendor for special requests or handling for the ordered good or service.
OB10BuyerId string - A unique buyer account on the OB10 network.
OB10TransactionId string - Unique Identifier for the Invoice transaction (generated by OB10).
OrgUnit1 string - The details from the Organization Unit fields. These may not have data, depending on configuration.
OrgUnit2 string - The details from the Organization Unit fields. These may not have data, depending on configuration.
OrgUnit3 string - The details from the Organization Unit fields. These may not have data, depending on configuration.
OrgUnit4 string - The details from the Organization Unit fields. These may not have data, depending on configuration.
OrgUnit5 string - The details from the Organization Unit fields. These may not have data, depending on configuration.
OrgUnit6 string - The details from the Organization Unit fields. These may not have data, depending on configuration.
PaymentAdjustmentNotes string - Notes to the vendor regarding the amount paid (underpayment due to damages, for example).
PaymentAmount string - Represents the amount of the payment that will be/has been made for the Invoice.
PaymentDueDate string - The date the vendor needs to be paid by.
PaymentTermsDays string - This number, along with type of payment terms (example: NET), determine when the invoice is expected to be paid.
ProvincialTaxId string - The Vendor Provincial Tax ID.
PurchaseOrderId string - The ID of the Purchase Order to which the Invoice should be matched. This value is required if none of the following are provided: LedgerCode; EmployeeLoginId, EmployeeId, EmployeeEmail, ExternalPolicyId.
ReceiptConfirmationType string - A code which indicates the receipt confirmation type for this Invoice (Invoice Confirmation, for example). Use GET /invoice/localizeddata to translate the code into text.
ShippingAmount string - The value for the Shipping Amount header field.
TaxAmount string - The value for the Tax Amount header field.
VatAmountOne string - The amount of VAT included in the invoice total (first of two VAT amount fields available).
VatAmountTwo string - The amount of VAT included in the invoice total (second of two VAT amount fields available).
VatRateOne string - The VAT rate applied to the net invoice total (should relate to the first VAT amount field).
VatRateTwo string - The VAT rate applied to the net invoice total (should relate to the second VAT amount field).
VendorRemitToIdentifier object VendorRemitToIdentifier Required Used to identify the vendor location for payment remittance. At a minimum, the VendorCode or the combination of (VendorName, Address1, and PostalCode) are required. Use of as many fields as possible is encouraged to ensure a single vendor can be identified. If more than one vendor matches the information provided, the Invoice creation attempt will fail.
VendorShipFromAddressCode string - The code which identifies the location from which the vendor shipped items listed in the invoice.
VendorTaxId string - The Vendor Tax ID.

LineItem

Name Type Format Description
Allocations array Allocation The details of the Invoice allocation fields.
AmountWithoutVat string - The net amount of the line item (excluding VAT).
Custom1 through Custom20 string - The details from the Custom fields. These may not have data, depending on configuration.
Description string - Brief overview of the good or service ordered.
ExpenseTypeCode string - A code which indicates the Expense Type for the Line Item.
ItemCode string - Represents the item code (the unique code a vendor assigns to a good or code a vendor assigns to a good or service to identify it).
MatchedPurchaseOrderReceipts array MatchedPurchaseOrderReceipt The details of the Matched Purchase Order Receipts Identity Fields (if any).
PurchaseOrderNumber string - Purchase Order that is associated to the Line Item .
Quantity string - Total number of goods or services ordered.
ShipFromPostalCode string - The postal code the good or service was shipped from.
ShipToPostalCode string - The postal code the good or service will be shipped to.
SupplierPartId string - The unique identifier provided by the supplier that is associated with the good or service.
Tax string - The tax associated with the line item.
TotalPrice string - The total amount of the line item.
UnitOfMeasure string - The code for the measurement unit used to quantify the good or service. Use GET /invoice/localizeddata to look up codes and descriptions.
UnitPrice string - The cost for a single unit of the line item good or service.
VatAmount string - The amount of VAT included in the line item total.
VatRate string - The VAT rate applied to the net line item total.

Allocation

Name Type Format Description
Custom1 through Custom7 string - The details from the Custom fields. These may not have data, depending on configuration.
Custom8 string - A value that can be applied to a custom field 8 that is part of the allocation form.
Custom9 string - A value that can be applied to a custom field 9 that is part of the allocation form.
Custom10 string - A value that can be applied to a custom field 10 that is part of the allocation form.
Custom11 through Custom20 string - The details from the Custom fields. These may not have data, depending on configuration.
Percentage string - Required The percentage of the Request Line Item that the individual allocation record. All Allocations associated to a given Line Item should add up to 100.

MatchedPurchaseOrderReceipt

Name Type Format Description
GoodsReceiptNumber string - The identifier of the purchase order goods receipt number to which the Invoice line item is matched.

VendorRemitToIdentifier

Name Type Format Description
Address1 string - Line 1 of the street address.
AddressCode string - The code which identifies a particular vendor location.
Name string - The name of the vendor.
PostalCode string - The postal / zip code.
VendorCode string - The code which identifies a particular vendor.

Invoice Pay v4

Invoice Pay v4 - Overview

SAP Concur partners with external payment providers for processing invoice payments. These payment providers are listed on the App Center and can integrate with the Invoice product by using the Invoice Pay APIs. Payment providers can get a list of all the payments authorized to be processed by them, and send back status of those payments.

Limitations: This API is only available for use by payment partners who will be processing invoice payments. This API can accept a maximum of 1,000 requests per minute across all payment providers. This API is available only in the North America Data Center.

Invoice Pay v4 - Process Flow

A process flow diagram of the Invoice Pay API

Invoice Pay v4 - Products and Editions

Invoice Pay v4 - Scope Usage

Name Description Endpoint
invoice.providerpayment.write Read access to pending payments, and write access to payment status GET,POST

Invoice Pay v4 - Dependencies

This API can only be used with SAP Concur clients who have purchased Concur Invoice.

Invoice Pay v4 - Access Token Usage

This API supports only Company access tokens.

Invoice Pay v4 - Obtaining payments

Payment providers can use this endpoint to get a list of payments. * This method will return all payments with a status PENDING_RETRIEVAL and payment method PAVPVD. After an invoice is approved and extracted it will be converted into a payment with status PENDING_RETRIEVAL. * It returns a maximum of 500 records at a time. In order to ensure that all payments are retrieved, call this method until you receive an empty payment in the response. * The payment provider will need to acknowledge that payments were received, using Updating a Payment With Status and updating the status of the payment to any status other than PENDING_RETRIEVAL.

Request

URI

Template
GET https://us.api.concursolutions.com/invoice/provider-payment/v4/payments

Headers

Payload

None.

Response

Status Codes

Headers

Payload

Payments

Example

Request

GET https://us.api.concursolutions.com/invoice/provider-payment/v4/payments
Accept: application/json
Authorization: BEARER {token}

Response

200 OK
Content-Type: application/json
{
  "payments": [
    {
      "paymentId": "0f27533f-ce38-4f43-a2f3-fa9f0e6b33fc",
      "paymentMethod": "PAYPVD",
      "paymentDueDate": "2018-08-09",
      "totalAmount":{
        "amount": "30.00",
        "currency": "USD"
      },
      "invoices": [
        {
          "invoiceNumber": "AGH87",
          "invoiceID": "1ADFBB440D7045F68DE2",
          "invoiceAmount":{
            "amount": "30.00",
            "currency": "USD"
          },
          "paymentAmount":{
            "amount": "30.00",
            "currency": "USD"
          },
          "notesToSupplier": null
        }
      ],
      "vendor":{
        "addressLine1": "1234 Rain Street",
        "addressLine2": null,
        "addressLine3": null,
        "vendorAddrCode": "1160",
        "city": "Chicago",
        "state": "IL",
        "postalCode": "60680-28160",
        "countryName": "UNITED STATES",
        "countryCode": "US",
        "firstName": "Terry",
        "lastName": "Brown",
        "phoneNumber": null,
        "email": "terry.brown@example.com",
        "vendorCode": "1160",
        "vendorName": "Dell",
        "buyerAccountNumber": "1234567890"
      }
    }
  ]
}

Updating a Payment With Status

Payment providers can use this endpoint to provide updates to the status of payments.

Request

URI

Template
POST https://us.api.concursolutions.com/invoice/provider-payment/v4/payments/{paymentId}

Parameters

Name Type Format Description
paymentId string - Required The identifier of the payment to update.

Headers

Payload

Payment Update

Response

Status Codes

Headers

Payload

Payment Update Result

Example

Request

POST https://us.api.concursolutions.com/invoice/provider-payment/v4/payments/0f27533f-ce38-4f43-a2f3-fa9f0e6b33fc
Authorization: BEARER {token}
Content-Type: application/json
{
  "providerReference" : "hdoesofdl",
  "status" : "PAID",
  "statusMessage" : "Payment was successful",
  "paymentAdjustmentNotes" : null,
  "statusDate" : "2018-05-10",
  "paymentInitiationDate" : "2018-05-09",
  "paymentSettlementDate" : "2018-05-09",
  "thirdPartyPaymentIdentifier" : "69249",
  "paymentMethod" : "CHECK",
  "paidAmount" : {
    "amount": "30.00",
    "currency": "USD"
  }
}

Response

200 OK
Content-Type: application/json
{
  "createdDate" : "2018-05-09",
  "lastModifiedDate" : "2018-05-09",
  "status" : "PAID",
  "statusMessage" : "Payment was successful",
  "paymentAdjustmentNotes" : null,
  "statusDate" : "2018-05-10",
  "paymentInitiationDate" : "2018-05-09",
  "paymentSettlementDate" : "2018-05-09",
  "thirdPartyPaymentIdentifier" : "69249",
  "paymentMethod" : "CHECK",
  "paidAmount" : {
    "amount": "30.00",
    "currency": "USD"
  }
}

Invoice Pay v4 - Schema

Payments

Name Type Format Description
payments array Payment Array of payments.

Payment

Name Type Format Description
invoices array Invoice Array of invoices that need to be batched in a payment.
paymentDueDate string YYYY-MM-DD The date by which the payment should be made.
paymentID string - Unique identifier of the payment in SAP Concur. Maximum 36 characters.
paymentMethod string - The value is always PAYPVD which means that the client wants to pay using a payment provider. Maximum 15 characters.
totalAmount object Amount This amount needs to be paid to the vendor.
vendor object Vendor Vendor requesting the payment.

Invoice

Name Type Format Description
invoiceAmount object Amount Amount on the invoice.
invoiceNumber string - Invoice Number. Maximum 50 characters.
invoiceId string - Unique identifier of the invoice in SAP Concur. This can be used to get additional invoice information from other APIs. This is the same as paymentRequestID in other Invoice APIs. Maximum 20 characters.
notesToSupplier string - Notes to the supplier contain remittance information that the buyer wants to provide to the supplier. Maximum 500 characters.
paymentAmount object Amount Payment amount on the invoice.

Vendor

Name Type Format Description
buyerAccountNumber string - Buyer Account Number. Maximum 50 characters.
vendorCode string - Vendor Code. Maximum 32 characters.
vendorName string - Vendor Name. Maximum 255 characters.
addressLine1 string - Vendor Address line 1. Maximum 255 characters.
addressLine2 string - Vendor Address line 2. Maximum 255 characters.
addressLine3 string - Vendor Address line 3. Maximum 255 characters.
city string - Vendor Address City. Maximum 255 characters.
state string - Vendor Address State. Maximum 10 characters.
countryCode string - Vendor Address Country Code. Maximum 2 characters.
countryName string - Vendor Address Country Name. Maximum 64 characters.
postalCode string - Vendor Address Postal Code. Maximum 20 characters.
vendorAddrCode string - Vendor Address Code. Maximum 64 characters.
email string - Email Address. Maximum 255 characters.
firstName string - First Name. Maximum 255 characters.
lastName string - Last Name. Maximum 255 characters.
phoneNumber string - Phone Number. Maximum 25 characters.

Amount

Name Type Format Description
amount string - Amount. Maximum 20 characters.
currency string - Currency Code. Maximum 3 characters.

Payment Update

Name Type Format Description
providerReference string - Unique identifier of the payment in the payment provider's system. This will be used for internal troubleshooting. Maximum 100 characters.
status string Payment Update Status Required Used to depict success, error or any other intermediate state, defined by SAP Concur.
statusMessage string - Payment provider description of the status. Providers can supply any message. Maximum 255 characters.
paymentAdjustmentNotes string - Payment adjustment notes sent by the payment provider. Maximum 255 characters.
statusDate string YYYY-MM-DD Required The date that the payment provider recorded this status change.
paymentInitiationDate string YYYY-MM-DD The date the payment was initiated.
paymentSettlementDate string YYYY-MM-DD The date the payment will be in the payees account.
thirdPartyPaymentIdentifier string - Check number if the payment was done via check or trace number for ACH payments. Maximum 255 characters.
paymentMethod string Payment Provider Method Required if the status is PAID, CHECK_PROCESSED, or CARD_SETTLED Payment method used by the payment provider.
paidAmount object Amount Required if the status is PAID, CHECK_PROCESSED, or CARD_SETTLED Amount paid by the payment provider.

Payment Update Result

Name Type Format Description
createdDate string YYYY-MM-DD The date the payment was created.
lastModifiedDate string YYYY-MM-DD The date the payment was last modified.
providerReference string - Unique identifier of the payment in the payment provider's system. Maximum 100 characters.
status string Payment Update Status Required Used to depict success, error or any other intermediate state, defined by SAP Concur.
statusMessage string - Payment provider description of the status. Providers can supply any message. Maximum 255 characters.
paymentAdjustmentNotes string - Payment adjustment notes sent by the payment provider. Maximum 255 characters.
statusDate string YYYY-MM-DD Required The date that the payment provider recorded this status change.
paymentInitiationDate string YYYY-MM-DD The date the payment was initiated.
paymentSettlementDate string YYYY-MM-DD The date the payment will be in the payees account.
thirdPartyPaymentIdentifier string - Check number if the payment was done via check or trace number for ACH payments. Maximum 255 characters.
paymentMethod string Payment Provider Method Required if the status is PAID, CHECK_PROCESSED, or CARD_SETTLED Payment method used by the payment provider.
paidAmount object Amount Required if the status is PAID, CHECK_PROCESSED, or CARD_SETTLED Amount paid by the payment provider.

Errors

Name Type Format Description
errors array Error An array of errors.

Error

Name Type Format Description
errorCode string - Required Machine readable code associated with the error.
errorMessage string - Required Human readable message associated with the error.

Invoice Pay v4 - Definitions

Payment Update Status

Value Description Status available in the Payment Confirmation Extract
PENDING_RETRIEVAL Not yet retrieved by the payment provider Not available
RETRIEVED Retrieved by the payment provider Not available
PROCESSING Payment is being processed by the payment provider Not available
REJECTED Payment was rejected by the payment provider Not available
RETURNED Payment was returned by the bank Not available
CANCELED Payment was canceled FAILED
CHECK_PRINTED Check was printed Not available
CHECK_MAILED Check was mailed Not available
CHECK_PROCESSED Check was processed PAID
CHECK_VOIDED Check was voided VOID
PAID Payment was successfully made PAID
CARD_EMAIL_SENT Email with card information sent to vendor Not available
CARD_AUTHORIZED Card was authorized by the merchant Not available
CARD_SETTLED Card was settled by vendor PAID

Payment Provider Method

Value Description
ACH ACH payment
CHECK Check payment
WIRE Wire payment
CARD Virtual Card payment
OTHER Any other payment method

Purchase Orders v3

The Purchase Orders API gives SAP Concur clients the ability to leverage external data to create and update approved purchase orders. Clients can build a direct connection to the Purchase Orders API which will create purchase orders for invoices to be associated to. It also allows clients to update created purchase orders when orders change, need to be closed, or identify and resolve matching exceptions on PO invoices.

Limitations: This API is not available in the China Data center. This API is only available for direct integrations with an existing SAP Concur client. This API can only be used to create new purchase requests and get the details of the created purchase request. This API cannot update, edit, or delete purchase requests. All edits or processing of the purchase request after it is sent to SAP Concur and created must be done in SAP Concur.

Purchase Orders v3 - Products and Editions

Purchase Orders v3 - Scope Usage

Required Scopes:

Name Description Endpoint
INVPO Create, update, and retrieve purchase orders. POST, PUT, GET

Purchase Orders v3 - Dependencies

SAP Concur clients must purchase Concur Invoice, Concur Purchase Order, and Concur Web Services in order to use this API. Concur Invoice with Concur Purchase Order must be configured before using this API.

To create purchase orders, you need to supply a Vendor Code and Vendor Address Code. You can access Vendor Manager in Concur Invoice to see these values. If you need to get this data from SAP Concur using web services, you can use the Vendor v3 API.

If your purchase order form in SAP Concur has required custom fields that are tied to lists, you will need to supply the Item Code for the list items. You can access List Management in SAP Concur to see your list items and list item codes. If you need to get this data from SAP Concur using web services, you can use the List Item v3 API to retrieve the Level1Code value for the list items.

Purchase Orders v3 - Access Token Usage

This API will work with both company or user access tokens. A company access token is required if the integration will create purchase orders for multiple requestors. Using a user access token to create purchase order results in the purchase order being assigned to the user that generated the user access token, not the user set in the payload. A user access token can be used for testing purposes.

Create a New Purchase Order

POST /api/v3.0/invoice/purchaseorders

Create or update a Purchase Order. Batch processing is not available using the Purchase Order API. Please use Import Jobs for batch updates.

Payload

Example

{
  "BillToAddress": {
    "Address1": "add1",
    "Address2": "add2",
    "Address3": "add3",
    "City": "city",
    "CountryCode": "US",
    "ExternalID": "billtoapi",
    "Name": "billto",
    "PostalCode": "55426",
    "StateProvince": "MN"
  },
  "CurrencyCode": "USD",
  "OrderDate":"2011-08-12T20:17:46.384Z",
  "ID": "API101",
  "IsTest": "false",
  "IsChangeOrder": "false",
  "LedgerCode": "23",
  "LineItem": [
    {
      "Allocation": [
        {
          "Amount": "106.74",
          "Percentage":"100.00000000",
          "GrossAmount":"106.74"
        }
      ],
      "CreateDate": "2019-12-13 20:00:37.0",
      "Description": "line 1",
      "ExpenseType": "Advertising",
      "ExternalID": "API100line1",
      "IsReceiptRequired": "true",
      "LineNumber": "1",
      "PurchaseOrderReceiptType": "WQTY",
      "Quantity": "1.00",
      "UnitOfMeasureCode":"DA",
      "UnitPrice": "106.74"
    }
  ],
  "Name": "poName",
  "PolicyExternalID": "PO",
  "PurchaseOrderNumber": "API101",
  "PurchaseRequestNumber": "100001",
  "RequestedBy": "Deo, John",
  "Shipping": "0.00000000",
  "ShipToAddress": {
    "Address1": "add1",
    "Address2": "add2",
    "Address3": "add3",    
    "City": "cityship",
    "CountryCode": "US",
    "ExternalID": "Shiptoapi",
    "Name": "shiptoapi",
    "PostalCode": "55426",
    "StateProvince": "MN"
  },
  "Status": "Transmitted",
  "Tax": "0.00000000",
  "URI": "http://www.concursolutions.com/api/v3.0/invoice/purchaseorders/purchaseorders/API101",
  "VendorCode": "VEN1",
  "VendorAddressCode": "VEN1ADDR1"
}

Response

Update Purchase Order Line Item With Receipt Information

PUT /api/v3.0/invoice/purchaseorderreceipts

Payload

Response

Purchase Orders v3 - Update an Existing Purchase Order

PUT /api/v3.0/invoice/purchaseorders

Payload

Response

Purchase Orders v3 - Get an Existing Purchase Order

GET /api/v3.0/invoice/purchaseorders/{id}

Parameters

Name Type Format Description
id string {id} The identifier for the purchase order.

Input

None

Response

Purchase Orders v3 - Schema

purchaseOrder

Name Type Format Description
AmountWithoutVat string - The net amount of the purchase order (excluding VAT).
BillToAddress object BillToAddress Required The customer's billing address, which is where the vendor should send the bill.
CurrencyCode string - Required The 3-letter ISO 4217 currency code of the currency that is associated with the purchase order.
Custom1 through Custom24 string - A value that can be applied to a custom field that is part of the purchase order header form.
Description string - A description of the purchase order.
DiscountPercentage string - The discount from the vendor, if the discount terms are met.
DiscountTerms string - The net discount terms that the vendor offers, when discounts apply.
ID string - The unique identifier of the resource.
IsTest string true / false If the purchase order is a test.
IsChangeOrder string true / false If the purchase order has a change order or not.
LedgerCode string - A code which indicates which company journal the Purchase Order is assigned to.
LineItem array LineItem Required The line items in a purchase order.
Name string - Required A name for the purchase order.
NeededByDate string YYYY-MM-DD The date by which the purchase order must be fulfilled.
OrderDate string YYYY-MM-DD Required The date when goods were ordered.
PaymentTerms string - The net payment terms that have been set up with a vendor.
PolicyExternalID string - Required The external identifier of the policy that should be associated with the purchase order. The external Id is a property of the policy configuration screen. Clients will need to get these ID’s from the Implementation team if using professional version. For standard version the value is always PO.
PoVendorTaxId string - The vendor tax ID.
ProvincialTaxId string - The vendor provincial tax ID.
PurchaseOrderNumber string - The purchase order number.
PurchaseRequestNumber string - The related purchase request number that generated the purchase order.
ReceiptType string - The purchase order receipt type (Deprecated). Use the PurchaseOrderReceiptType at line item level instead.
RequestedBy string - The person who requests the goods in the purchase order.
RequestedDeliveryDate string YYYY-MM-DD The date the purchase order instructed the vendor to deliver the goods.
Shipping string - The total shipping cost for the purchase order.
ShippingDescription string - A description of how the goods in the purchase order will ship. For example, via FedEx.
ShippingMethodKey string - A code that represents the shipping method used by the vendor. Maximum length: 10 characters
ShippingTermsKey string - A code that represents the shipping terms that the vendor offers. Maximum length: 10 characters
ShipToAddress object ShipToAddress Required The customer's shipping address, which is where the vendor should ship the goods.
Status string - The current status of the purchase order. Default: Transmitted. Supported values: Closed, Transmitted
Tax string - The total tax for the purchase order.
URI string - The URI to the resource.
VatAmountOne string - This field has not been implemented by Purchase Request yet. Any data in this field will be ignored.
VatAmountTwo string - This field has not been implemented by Purchase Request yet. Any data in this field will be ignored.
VatRateOne string - This field has not been implemented by Purchase Request yet. Any data in this field will be ignored.
VatRateTwo string - This field has not been implemented by Purchase Request yet. Any data in this field will be ignored.
VendorAccountNumber string - The vendor account number.
VendorAddressCode string - Required The code that identifies the vendor's remit address for the purchase order.
VendorCode string - Required The code that identifies the vendor for the purchase order.

BillToAddress

Name Type Format Description
Address1 string - Required Address line 1 of the billing address.
Address2 string - Address line 2 of the billing address.
Address3 string - Address line 3 of the billing address.
City string - Required The city of the billing address.
CountryCode string - Required The code of the country for the billing address.
ExternalID string - Required A unique value supplied by the customer to identify a particular billing address.
Name string - An optional name that can be given to the billing address.
PostalCode string - Required The postal code of the billing address.
StateProvince string - Required The state or province of the billing address.

LineItem

Name Type Format Description
AccountCode string - The account code of the line item. A value must be supplied for either ExpenseType or AccountCode, but not both. This field is required if an ExpenseType value is not supplied.
Allocation array Allocation A list of the allocations that are associated with the line item. Allocation elements can be repeated within the same line items to represent multiple allocations.
AmountWithoutVat string - The net amount of the line item (excluding VAT).
CreateDate string YYYY-MM-DD The date the line item was created.
Custom1 through Custom20 string - A value that can be applied to a custom field 1 that is part of the purchase order line item form.
Description string - A description of the line item.
ExpenseType string - The expense type of the line item. A value must be supplied for either ExpenseType or AccountCode, but not both. This field is required if an AccountCode value is not supplied.
ExternalID string - Required A customer-supplied value that uniquely identifies the line item within the purchase order.
IsReceiptRequired string true / false Indicates whether the line item requires a receipt.
LineNumber string - Required The line item number within the purchase order.
Quantity string - Required The quantity associated with the line item.
PurchaseOrderReceiptType string - Purchase order ReceiptType of the line item. If you are using Concur Receiving and need to enter Goods Receipts against the resulting PO lines use QUANTITY_RECEIPT. Default: NONE. Supported values: QUANTITY_RECEIPT, NONE
RequestedBy string - The person who requests the goods in the line item of the purchase order.
RequestedDeliveryDate string YYYY-MM-DD The date the line item of the purchase order instructed the vendor to deliver the goods.
SupplierPartID string - Any number that might help to identify the line item. This could be a value such as the vendor's part number or even the manufacturer number.
Tax string - Any tax that is associated with the line item.
UnitOfMeasureCode string - The unit of measure code of the line item.
UnitPrice string - Required The price of each item of the line item.
VatAmount string - This field has not been implemented by Purchase Request yet. Any data in this field will be ignored.
VatRate string - This field has not been implemented by Purchase Request yet. Any data in this field will be ignored.

Allocation

Name Type Format Description
Amount string - Required The total amount of the allocation.
Custom1 through Custom20 string - A value that can be applied to a custom field 1 that is part of the allocation form.
GrossAmount string - Required The allocation gross amount.
Percentage string - Required The allocation percentage.

ShipToAddress

Name Type Format Description
Address1 string - Required Address line 1 of the shipping address.
Address2 string - Address line 2 of the shipping address.
Address3 string - Address line 3 of the shipping address.
City string - Required The city of the shipping address.
CountryCode string - Required The code of the country for the shipping address.
ExternalID string - Required A unique value supplied by the customer to identify a particular shipping address.
Name string - An optional name that can be given to the shipping address.
PostalCode string - Required The postal code of the shipping address.
StateProvince string - Required The state or province of the shipping address.

Response Schema

Name Type Format Description
ErrorCode string - A code that indicates why the purchase order was not processed successfully.
ErrorMessage string - A description of the error.
FieldCode string - A code that indicates which field caused an issue. This code typically appears only when a field is being validated against a field of a form type. Format: LEVEL CODE. The possible levels are: Header, ShipTo, BillTo, LineItem, Allocation.
LineItemExternalID string - The external ID of a line item that caused an error. If the error is related to an allocation, this field indicates the external ID of the line item that the allocation is associated with, and also indicates the allocation that caused of the error.
Message string -
PurchaseOrderNumber string - The purchase order number.
Status string SUCCESS / FAILURE The result of processing the purchase order.

Receipt Schema

Name Type Format Description
IsReceived string - Required Indicates whether the line item was received.
LineItemExternalID string - Required A customer-supplied value that uniquely identifies the line item within the purchase order.
PurchaseOrderNumber string - Required The purchase order number.
ReceivedDate string YYYY-MM-DD The date the line item was received.
ReceivedQuantity string - The number of items that were received.

Error Codes

The web service will not return a 4xx HTTP response code for a batch operation even when every item in the batch failed to be created, updated or deleted. The client must inspect the response to look for warnings or errors with individual batch items.

Code Description
1000 The PO number is missing or invalid.
2000 There was no vendor found for the supplied Vendor Code and Vendor Address Code.
3000 The Currency Code is missing or invalid.
4000 There was no policy found matching the supplied External Id.
4001 The policy does not support purchase orders.
4002 The policy cannot be changed on the purchase order.
5000 The purchase order does not contain any line items.
5001 The line item must contain expense type or account code, but not both.
5002 The line item expense type is invalid.
5003 The line item account code is invalid.
5004 The line item tax and unit price must both match positive or negative.
5500 The line item contains an allocation, but no allocation form is defined.
5501 The line item allocation amounts exceed the line item total.
5502 The distribution amounts for a line item must match the line item amount positive or negative.
5503 The distribution amounts for a line item cannot be zero.
5600 The external id for the line item is not unique across the purchase order.
6000 The Ship To Address is missing or invalid.
6001 The Bill To Address is missing or invalid.
8000 A required field is missing.
8001 A field’s value exceeds the maximum length allowed.
8002 A field’s value is not the correct data type.
8003 A field’s value is an invalid list item.
8004 A field’s value is an invalid connected list item.
8005 The Country Code is missing or invalid.
8006 A value was supplied for a field that is not part of the form.
9999 An unexpected error occurred.

Purchase Request v4 - Get Started

The Purchase Request API gives SAP Concur clients the ability to leverage external data to create purchase requests for pre-authorization of purchase orders. Clients can build a direct connection to the Purchase Request API which will create new purchase requests and automatically submit them into the pre-authorization workflow. Once approved, the purchase request results in a purchase order that can be transmitted to a vendor from SAP Concur.

Use Case

Many Concur Invoice clients have external systems that have part or service lists with pricing. If they use SAP Concur pre-authorization using purchase request, the data from the external systems must be entered manually into the purchase request cart and submitted for approval by the requesting employee. Using this API and a client-built integration, the requestor can browse and select the items from the external system with quantities and other details needed, and then send the data to SAP Concur. A purchase request will be created and submitted into the workflow. The API returns a response message with a record identifier (URI), which can be used with the Get Purchase Request Details method to get the basic details of the created purchase request: Concur Purchase Request number, workflow status, exceptions, and once approved, the resulting SAP Concur purchase order number.

Limitations

This API is not available in the China Data center. This API is only available for direct integrations with an existing SAP Concur client. If you are a Partner looking to build an App Center App using this API, please reach out to your SAP Concur Representative. This API can only be used to create new purchase requests and get the details of the created purchase request. This API cannot update, edit, or delete purchase requests. All edits or processing of the purchase request after it is sent to SAP Concur and created must be done in SAP Concur.

Purchase Request v4 - Get Started - Regional Availability

https://us.api.concursolutions.com/purchaserequest/v4/
https://emea.api.concursolutions.com/purchaserequest/v4/

Purchase Request v4 - Get Started - Products and Editions

Purchase Request v4 - Get Started - Scope Usage

Name Description Endpoint
purchaserequest.write Allows you to create new purchase requests POST
purchaserequest.read Allows you to retrieve purchase requests GET

Purchase Request v4 - Get Started - Dependencies

SAP Concur clients must purchase Concur Invoice, Concur Purchasing, and Concur Web Services in order to use this API. Concur Invoice with Concur Purchasing must be configured before using this API.

To create purchase requests, you need to supply a Vendor Code and Vendor Address Code. You can access Vendor Manager in Concur Invoice to see these values. If you need to get this data from SAP Concur using web services, you can use the Vendor v3 API.

If your purchase request form in SAP Concur has required custom fields that are tied to lists, you will need to supply the Item Code for the list items, or configure them to copy down from another source such as Employee. You can access List Management in SAP Concur to see your list items and list item codes. If you need to get this data from SAP Concur using web services, you can use the List Item v3 API to retrieve the Level1Code value for the list items.

Purchase Request v4 - Get Started - Access Token Usage

This API will work with both Company or User access tokens, however a Company access token is required if the integration will create purchase requests for multiple requestors. Using a User access token to create purchase requests results in the purchase request being assigned to the user that generated the User access token, not the user set in the payload. A User access token can be used for testing purposes.

Retrieve a Company Access Token

Clients connecting to this API to build a custom integration will receive client credentials and information on how to generate your Company access token or Company refresh token from your Concur Technical Enablement resource.

Retrieve a User Access Token

This API supports User access tokens, however any purchase requests created using a User access token will only create/assign these requests to the user that generated the User access token. Before making requests to the Purchase Request API, you must obtain an access token from the Authentication API.

The response will include an access_token field, which contains your access token. For subsequent calls, you will need to include this access token in the Authorization header of your calls. An id_token will be also included in the response. In order to retrieve the unique ID for your user, you will have to decode this id_token at jwt.io. You will need this ID in order to post Purchase Requests.

Purchase Request v4 - Endpoints

Version

4.0

Purchase Request v4 - Endpoints - Create a New Purchase Request

Create a Purchase Request based on provided header and line item details. If the request is valid it creates a purchase request and returns back a unique identifier to get the purchase request details.

Scopes

purchaserequest.write - Refer to Scope Usage for full details.

Request

URI

Template

POST /purchaserequest/v4/purchaserequests

Parameters

None

Headers

Payload

Response

Status Codes

Headers

Payload

Example

Request

This is a sample set of fields. The fields and values your entity requires will vary based on your edition of Concur Invoice, and your forms and fields configuration. This example includes commonly used fields.

POST /purchaserequest/v4/purchaserequests
Authorization: Bearer {token}
Content-Type: application/json
{
  "description" : "New office supplies",
  "userLoginId" : "john.deo@concur",
  "policyExternalId" : "po-external-id",
  "currencyCode" : "USD",
  "notesToSupplier" : "Office space request phase 1",
  "comments" : "office supplies request",
  "custom1" : "ADVT",
  "shipToAddressCode" : "SHIP15139",
  "billToAddressCode" : "MNSLP129",
  "lineItems" : [
    {
      "purchaseType" : "SERVICES",
      "vendorCode" :"VEN1",
      "vendorAddressCode" : "ADDR1",
      "description" : "monitor",
      "quantity" : "20",
      "unitPrice" : "154.4",
      "expenseType" : "1250",
      "receiptType" : "NONE",
      "neededByDate": "2018-06-28",
      "uomCode" : "DA",
      "shipping" : "13.5",
      "tax" : "11",
      "supplierPartId" : "DAQT1",
      "url" :[
        "http://officesupplies.com/monitor"
      ],
      "notesToVendor" : "Phase 1 request monitor",
      "comments" : "Phase 1 request for new employees for monitor",
      "custom2" : "LGVT1"
    },
    {
      "purchaseType" : "GOODS",
      "vendorCode" :"VEN1",
      "vendorAddressCode" : "ADDR1",
      "description" : "office chair",
      "quantity" : "20",
      "unitPrice" : "346.2",
      "expenseType" : "1251",
      "receiptType" : "QUANTITY_RECEIPT",
      "neededByDate": "2018-06-28",
      "uomCode" : "DA",
      "shipping" : "15",
      "tax" : "17.5",
      "supplierPartId" : "DAQT2",
      "url" :[
        "http://officesupplies.com/officechair"
      ],
      "notesToVendor" : "Phase 1 request office chair",
      "comments" : "Phase 1 request for new employees for office chair",
      "custom3" : "DEPT",
      "custom4" : "SALES"
    }
  ]
}

Response

HTTP/1.1 202 Accepted
Content-Type: application/json
Date: date-requested
Content-Length: 1000
concur-correlationid: 1234abcd-12ab-34cd-56ef-123456abcdef
{
  "id" : "b1e22581-ff4a-48e9-981b-2f5065579096",
  "uri": "http://us.api.concursolutions.com/purchaserequest/v4/purchaserequests/b1e22581-ff4a-48e9-981b-2f5065579096?mode=COMPACT"
}

Purchase Request v4 - Endpoints - Get Purchase Request Details

Gets purchase request details. The supported mode is COMPACT, which returns basic info about the purchase request along with any exceptions.

Scopes

purchaserequest.read - Refer to Scope Usage for full details.

Request

URI

Template

GET /purchaserequest/v4/purchaserequests/{id}?mode=COMPACT

Parameters

Name Type Format Description
mode string - Required: Specifies mode for Get Purchase Request Details. Supported value: COMPACT

Headers

Payload

None

Response

Status Codes

Headers

Payload

Example

Request

GET /purchaserequest/v4/purchaserequests/de9c0894-b807-6943-8e3f-49a707da3456?mode=COMPACT
Authorization: Bearer {token}
Content-Type: application/json

Response

HTTP/1.1 200 OK
Content-Type: application/json
Date: date-requested
Content-Length: 1000
concur-correlationid: 1234abcd-12ab-34cd-56ef-123456abcdef
{
  "purchaseRequestId" : "de9c0894-b807-6943-8e3f-49a707da3456",
  "purchaseRequestNumber" : "100000",
  "purchaseRequestQueueStatus" : "CREATED",
  "purchaseRequestWorkflowStatus" : "Approved",
  "purchaseRequestExceptions": [
    {
      "message": "Line Item Quantity does not match",
      "eventCode": "PURCH_DETAIL_ITEM_SAVE",
      "exceptionCode": "0070071",
      "isCleared": false,
      "prExceptionId": "fe636831-43a1-9540-bf86-32e2c19400af"
    }
  ],
  "purchaseOrders": [
    {
      "purchaseOrderNumber": "PO10001"
    }
  ]        
}

Purchase Request v4 - Endpoints - Schema

Create Purchase Request Schema

Name Type Format Description
userId string - Required: The employee that is requesting the items. This is the UUID of the employee. Either UserId or UserEmail or UserLoginId is required to identify the employee.
userEmail string - Required: The employee that is requesting the items. This is the employee's email. Either UserId or UserEmail or UserLoginId is required to identify the employee.
userLoginId string - Required: The employee that is requesting the items. This is the employee's Login Id. Either UserId or UserEmail or UserLoginId is required to identify the employee.
description string - A description of the purchase request.
policyExternalId string - The external identifier of the policy that should be associated with the purchase request. If not supplied, the API will use the default policy set up for the user group assigned to the requesting employee. This is the External Id from the Invoice Policy configuration. Clients will need to get these Ids from their SAP Concur contact if they need to assign policies other than the group default.
currencyCode string - Required: The 3-letter ISO 4217 currency code of the currency that is associated with the purchase request. This code will be used for all items on this request. Example: USD
notesToSupplier string - Notes to print on the transmitted purchase order PDF sent to the supplier.
comments string - Internal comments related to this record.
custom1 through custom24 string - Each custom field used should have its own row in the message. If the field is tied to a connected list, the accepted value is the list Item Code configured for the list in SAP Concur.
shipToAddressCode string - The shipping address of the Purchase Request. The accepted value is the address code from ShipTo record. If not supplied, the API will use the requesting user's default shipping address.
billToAddressCode string - The billing address of the Purchase Request to be used for invoicing. The accepted value is the address code from the BillTo record. If not supplied the API will use the policy's default BillTo address.
lineItems array LineItem Required: Requested items or services related to this Purchase Request.

LineItem

Name Type Format Description
purchaseType string - Required: The type of item, either goods or services. Displayed as Type in Concur Invoice. Supported values: GOODS, SERVICES.
vendorCode string - Required: The code that identifies the vendor. This value can be found in the vendor information form of Vendor Manager. This is used along with Vendor Address Code to determine the specific Vendor record.
vendorAddressCode string - Required: The code that identifies the vendor's address. This value can be found in the vendor information form of Vendor Manager and is labeled Address Accounting Code. This is used along with Vendor Code to determine the specific Vendor record.
description string - Required: A description of the line item.
quantity decimal - Required: The quantity associated with the line item.
unitPrice decimal - Required: The unit price of the line item.
expenseType string - The PET code of the Expense Type that will be assigned to the line item. If not supplied it will default to the Expense Type set up on the Vendor Profile used for the item. Clients will need to get these PET codes from their SAP Concur contact.
receiptType string - The type of receipt. If not supplied, the API will use the purchaseType to set this field to NONE for SERVICES, or QUANTITY_RECEIPT for GOODS. If you are using SAP Concur Receiving and need to enter Goods Receipts against the resulting PO lines use QUANTITY_RECEIPT. Supported values: QUANTITY_RECEIPT, NONE.
neededByDate date YYYY-MM-DD The date by which the purchase order must be fulfilled. Example: 2018-03-23
uoMCode string - Unit of Measure (UOM) code for the purchase request item. Accepted values are the UOM Codes set up in the Unit of Measure configuration in Concur Invoice. If not supplied, the API will default a UOM based on the defaults for goods and services.
shipping decimal - The total shipping cost for the item.
tax decimal - Tax amount that is associated with the line item.
supplierPartId string - An Id value that helps to identify the line item. This could be a value such as the vendor’s part number or the manufacturer number.
url array - A URL related to the item. You can have multiple URLs per item, enclosed in quotes and comma separated.
notesToVendor string - Notes related to the item that display on the transmitted purchase order PDF to the vendor.
comments string - Internal comments related to this record.
custom1 through custom20 string - Each custom field used should have its own row in the message. If the field is tied to a connected list, the accepted value is the List Item Code configured for the list in SAP Concur.

Create Purchase Request Response Schema

Name Type Format Description
errors array Error An array of errors indicating which fields have failed validation.
id string - The unique purchase request reference ID if the request has passed all validations. This reference ID will be needed to look up details of the purchase request.
uri string - The URI to look up details of the newly created purchase request.

Get Purchase Request Response Schema

Name Type Format Description
purchaseRequestId string - The unique purchase request reference Id. Returned by the Create Purchase Request API call.
purchaseRequestNumber string - The unique purchase request identifier which can be used to uniquely identify a purchase request in SAP Concur products.
purchaseRequestQueueStatus string - The creation status of the purchase request. Possible values are: PENDING_CREATION, CREATED, CREATE_FAILED.
purchaseRequestWorkflowStatus string - The workflow status of the purchase request. Possible values are: Approved, Pending Approval, Pending Cost Object Approval, Sent Back To Employee, Not Submitted, Submitted, Pending Processor Review, Vendor Approval, Approval Time Expired.
purchaseOrders array PurchaseOrders If the purchase request has been approved and a purchase order generated, this array contains the purchase order details. If empty, this element will not be returned.
purchaseRequestExceptions array PurchaseRequestExceptions An array of exceptions, if present on the purchase request. If empty, this element will not be returned.

PurchaseOrders

Name Type Format Description
purchaseOrderNumber string - The purchase order number.

PurchaseRequestExceptions

Name Type Format Description
eventCode string - The event code of the exception. Example: PURCH_DETAIL_SUBMIT
exceptionCode string - The unique exception code.
isCleared boolean - Whether the exception has been cleared.
prExceptionId string - The unique exception id of the purchase request.
message string - The message of the exception with details.

Purchase Request v4 - Endpoints - Error

Name Type Format Description
errorCode string - An error code indicating why a field failed validation.
errorMessage string - A description of the error.
dataPath string - The path to the request data which has the error message.

Error Codes When the HTTP Status Code is 4xx

ErrorCode Error Message
missingRequestBody Missing request body.
invalidRequestBody Passed request body is invalid.
missingUserInfo Either userID or userEmail or userLoginId is required.
invalidUserInfo Either userID or userEmail or userLoginId is invalid, or user does not have access to this resource.
provideOneUserInformation Either userID or userEmail or userLoginId is required.
missingCurrencyCode currencyCode is missing.
invalidCurrencyCode currencyCode is invalid.
invalidPolicyInformation Cannot find a purchase order policy with the supplied policyExternalId.
missingLineItems lineItems are missing.
invalidPurchaseType purchaseType is invalid.
missingPurchaseType purchaseType is required.
missingVendorAddressCode vendorAddressCode is required.
missingVendorCode vendorCode is required.
invalidVendor Vendor / Address code combination is invalid.
missingDescription Line item description is required.
missingQuantity Line item quantity is required.
invalidQuantity Line item quantity is invalid.
missingUnitPrice unitPrice is required.
invalidUnitPrice unitPrice is invalid.
invalidDateFormat Expected a date in the format YYYY-MM-DD.

Purchase Order Receipt v3

Purchase order receipts are records that indicate purchase order lines were completed and received. This API provides methods to create a new purchase order receipt, and retrieve, update, or delete an existing purchase order receipt.

Version

3.0

Create a new purchase order receipt

POST /api/v3.0/invoice/purchaseorderreceipts

Creates purchase order receipt, associates it to purchase order line item, and returns update status.

Parameters

Name Type Format Description
purchaseOrderReceipt - body The details of the purchase order receipt.

Input

Schema

{
  "Deleted": "false",
  "DeliverySlipNumber": "DSN1",
  "GoodsReceiptNumber": "RCPT1",
  "ID": "1000001",
  "LineItemExternalID": "LN000001",
  "PurchaseOrderNumber": "PO12345",
  "ReceivedDate": "2018-09-15 00:00:00.0",
  "ReceivedQuantity": "14.5",
  "UnitOfMeasureCode": "DA",
  "URI": "string",
  "Version": "2.0"
}

Response

Response schema

Update purchase order line item - receipt information

PUT /api/v3.0/invoice/purchaseorderreceipts

Parameters

Name Type Format Description
purchaseOrderReceipt - body Purchase order receipt information.

Input

Receipt schema

Response

Response schema

Get existing purchase order receipt

GET /api/v3.0/invoice/purchaseorderreceipts?purchaseOrderNumber=PO1&lineItemExternalID=L1&goodsReceiptNumber=GRN1

Parameters

Name Type Format Description
purchaseOrderNumber string {purchaseOrderNumber} The purchase order number.
lineItemExternalID string {lineItemExternalID} A customer-supplied value that uniquely identifies the line item within the purchase order.
goodsReceiptNumber string {goodsReceiptNumber} Goods receipt number for a purchase order line item receipt.

Input

None.

Response

Schema

Delete existing purchase order receipt

DELETE /api/v3.0/invoice/purchaseorderreceipts?purchaseOrderNumber=PO1&lineItemExternalID=L1&goodsReceiptNumber=GRN1

Parameters

Name Type Format Description
purchaseOrderNumber string {purchaseOrderNumber} The purchase order number.
lineItemExternalID string {lineItemExternalID} A customer-supplied value that uniquely identifies the line item within the purchase order.
goodsReceiptNumber string {goodsReceiptNumber} Goods receipt number for a purchase order line item receipt.

Input

None.

Response

Response schema

Purchase Order Receipt v3 - Response schema

Name Type Format Description
ErrorCode string - A code that indicates why the purchase order receipt was not processed successfully.
ErrorMessage string - A description of the error.
FieldCode string - A code that indicates which field caused an issue. This code typically appears only when a field is being validated against a field of a form type.
LineItemExternalID string - The external ID of a line item that caused an error.
Message string - Message of request result.
PurchaseOrderNumber string - The purchase order number.
Status string - The result of processing the purchase order receipt. Format: SUCCESS or FAILURE

Get Purchase Order Receipt schema

Name Type Format Description
purchaseOrderReceipt array PurchaseOrderReceipt Purchase Order Receipt.
NextPage string - The URI of the next page of results, if any.
TotalCount int - Total number of receipts.
Info string - Any additional information messages. Currently a maximum of 2000 PO receipts will be returned.

Purchase Order Receipt v3 - Receipt schema

Name Type Format Description
Deleted boolean - Delete status of purchase order line item receipt.
DeliverySlipNumber string - Delivery slip number for a purchase order line item receipt.
GoodsReceiptNumber string - Goods receipt number for a purchase order line item receipt.
ID string - The unique identifier of the resource.
LineItemExternalID string - Required A customer-supplied value that uniquely identifies the line item within the purchase order.
PurchaseOrderNumber string - Required The purchase order number.
ReceivedDate string - The date the line item was received. Format: YYYY-MM-DD
ReceivedQuantity string - The number of items that were received.
UnitOfMeasureCode string - Unit of measure code for a purchase order line item receipt.
URI string - The URI to the resource.
Version string - The version of purchase order line item receipt. Use Version 2.0 here unless doing receipt confirmation only.

Purchase Order Receipt v3 - Error codes

The Purchase Order Receipt API’s error responses

Code Description
1000 The PO number is missing or invalid.
1001 The External ID is missing or invalid.
1002 The Is Received is invalid. It must be either empty, Y/N, or y/n.
1003 The Received Quantity is invalid. It must be either empty or numeric.
1004 The Received Date is invalid. It must be either empty or date formatted YYYY-MM-DD.
1005 The Unit Of Measure code is invalid. It must be either empty or Valid with less than 10 chars in length.
1006 The Received Quantity is invalid, for Receipt Type WQTY on Purchase Order, Quantity is required. Sorry.
1007 The field is not part of the form
1008 The value exceeds the maximum length allowed for the field.
1009 The value is the wrong data type for the field.
1011 The invalid value expression.
9999 An unexpected error occurred.
10010 The required field is missing.

Sales Tax Validation v3

Limitations: This API is only available to partners who have been granted access by SAP Concur. Access to this documentation does not provide access to the API. This API is not available in Implementation environments.

Sales Tax Validation v3 - Products and Editions

Sales Tax Validation v3 - Scope Usage

Name Description Endpoint
INVTV Invoice - Tax Validation GET, PUT

Sales Tax Validation v3 - Dependencies

None.

Get Invoices for Calculating Tax

Retrieves invoices for calculating tax.

Scopes

INVTV - Refer to Scope Usage for full details.

Request

URI

Template
https://{datacenterURI}/api/v3.0/invoice/salestaxvalidationrequest

Parameters

Name Type Format Description
offset string query The starting point of the next set of results, after the limit specified in the limit field has been reached.
limit Int32 query The number of invoices to retrieve. Maximum value: 1,000
modifiedafter string query A parameter that can be used to limit the results to invoices modified after the specified date.

Payload

Response

Payload

Example

Request

https://us.api.concursolutions.com/api/v3.0/invoice/salestaxvalidationrequest

Response

{
    "TotalCount": 1,
    "Items": [
        {
            "RequestID": "3E6969DD15D64A349188",
            "TaxReferenceID": "9B8888FA54CA47E598081F4527A2BC50",
            "CountryCode": "US",
            "Title": "Test Request - 15 Feb",
            "PurchaseOrderNumber": null,
            "InvoiceDate": "2019-03-01 00:00:00.0",
            "StatusCode": null,
            "Status": null,
            "InvoiceAmount": "480.00000000",
            "Total": "500.00000000",
            "ShippingAmount": "0.00000000",
            "Tax": "20.00000000",
            "CalculatedTaxAmount": null,
            "CalculatedTaxRate": null,
            "CurrencyCode": "USD",
            "VendorInvoiceNumber": "99999",
            "OrgUnit1": "1",
            "OrgUnit1Value": "Best Buy",
            "OrgUnit2": "100",
            "OrgUnit2Value": "Geek Squad",
            "OrgUnit3": null,
            "OrgUnit3Value": null,
            "OrgUnit4": null,
            "OrgUnit4Value": null,
            "OrgUnit5": null,
            "OrgUnit5Value": null,
            "OrgUnit6": null,
            "OrgUnit6Value": null,
            "Custom1": null,
            "Custom1Value": null,
            "Custom2": null,
            "Custom2Value": null,
            "Custom3": null,
            "Custom3Value": null,
            "Custom4": null,
            "Custom4Value": null,
            "Custom5": null,
            "Custom5Value": null,
            "Custom6": null,
            "Custom6Value": null,
            "Custom7": null,
            "Custom7Value": null,
            "Custom8": null,
            "Custom8Value": null,
            "Custom9": null,
            "Custom9Value": null,
            "Custom10": null,
            "Custom10Value": null,
            "Custom11": null,
            "Custom11Value": null,
            "Custom12": null,
            "Custom12Value": null,
            "Custom13": null,
            "Custom13Value": null,
            "Custom14": null,
            "Custom14Value": null,
            "Custom15": null,
            "Custom15Value": null,
            "Custom16": null,
            "Custom16Value": null,
            "Custom17": null,
            "Custom17Value": null,
            "Custom18": null,
            "Custom18Value": null,
            "Custom19": null,
            "Custom19Value": null,
            "Custom20": null,
            "Custom20Value": null,
            "Custom21": null,
            "Custom21Value": null,
            "Custom22": "Default",
            "Custom22Value": "Default-Change to Client",
            "Custom23": null,
            "Custom23Value": null,
            "Custom24": null,
            "Custom24Value": null,
            "BillToAddress": {
                "ExternalID": null,
                "Name": null,
                "Address1": null,
                "Address2": null,
                "Address3": null,
                "City": null,
                "StateProvince": null,
                "State": null,
                "PostalCode": null,
                "CountryCode": null
            },
            "ShipToAddress": {
                "ExternalID": null,
                "Name": null,
                "Address1": "BTP",
                "Address2": null,
                "Address3": null,
                "City": "Bengaluru South",
                "StateProvince": null,
                "State": null,
                "PostalCode": "560093",
                "CountryCode": "IN"
            },
            "LineItem": [
                {
                    "CommodityCode": "95121513",
                    "Quantity": "1.00000000",
                    "LineItemKey": "gWo0fa6rk0zJkpaD3ZXHL8DbNaw",
                    "UnitPrice": "200.00000000",
                    "Total": "200.00000000",
                    "CountryCode": "US",
                    "CalculatedTaxAmount": null,
                    "CalculatedTaxRate": null,
                    "CurrencyCode": "USD",
                    "Allocations": {
                        "Allocation": [
                            {
                                "Custom1": "1",
                                "Custom1Value": null,
                                "Custom2": "100",
                                "Custom2Value": null,
                                "Custom3": null,
                                "Custom3Value": null,
                                "Custom4": null,
                                "Custom4Value": null,
                                "Custom5": null,
                                "Custom5Value": null,
                                "Custom6": null,
                                "Custom6Value": null,
                                "Custom7": null,
                                "Custom7Value": null,
                                "Custom8": null,
                                "Custom8Value": null,
                                "Custom9": null,
                                "Custom9Value": null,
                                "Custom10": null,
                                "Custom10Value": null,
                                "Custom11": null,
                                "Custom11Value": null,
                                "Custom12": null,
                                "Custom12Value": null,
                                "Custom13": null,
                                "Custom13Value": null,
                                "Custom14": null,
                                "Custom14Value": null,
                                "Custom15": null,
                                "Custom15Value": null,
                                "Custom16": null,
                                "Custom16Value": null,
                                "Custom17": null,
                                "Custom17Value": null,
                                "Custom18": null,
                                "Custom18Value": null,
                                "Custom19": null,
                                "Custom19Value": null,
                                "Custom20": null,
                                "Custom20Value": null,
                                "AllocationAmount": "200.00000000"
                            }
                        ]
                    },
                    "Vendor": {
                        "VendorCode": null,
                        "VendorName": "Holiday Inn",
                        "VendorAddressName": null,
                        "AddressCode": null,
                        "Address1": null,
                        "Address2": null,
                        "Address3": null,
                        "City": null,
                        "State": null,
                        "PostalCode": null,
                        "CountryCode": null
                    }
                },
                {
                    "CommodityCode": "90111501",
                    "Quantity": "1.00000000",
                    "LineItemKey": "gWo0c5$sMJswx4W0tK$pw2bwBTFtQ",
                    "UnitPrice": "280.00000000",
                    "Total": "280.00000000",
                    "CountryCode": "US",
                    "CalculatedTaxAmount": null,
                    "CalculatedTaxRate": null,
                    "CurrencyCode": "USD",
                    "Allocations": {
                        "Allocation": [
                            {
                                "Custom1": "1",
                                "Custom1Value": null,
                                "Custom2": "100",
                                "Custom2Value": null,
                                "Custom3": null,
                                "Custom3Value": null,
                                "Custom4": null,
                                "Custom4Value": null,
                                "Custom5": null,
                                "Custom5Value": null,
                                "Custom6": null,
                                "Custom6Value": null,
                                "Custom7": null,
                                "Custom7Value": null,
                                "Custom8": null,
                                "Custom8Value": null,
                                "Custom9": null,
                                "Custom9Value": null,
                                "Custom10": null,
                                "Custom10Value": null,
                                "Custom11": null,
                                "Custom11Value": null,
                                "Custom12": null,
                                "Custom12Value": null,
                                "Custom13": null,
                                "Custom13Value": null,
                                "Custom14": null,
                                "Custom14Value": null,
                                "Custom15": null,
                                "Custom15Value": null,
                                "Custom16": null,
                                "Custom16Value": null,
                                "Custom17": null,
                                "Custom17Value": null,
                                "Custom18": null,
                                "Custom18Value": null,
                                "Custom19": null,
                                "Custom19Value": null,
                                "Custom20": null,
                                "Custom20Value": null,
                                "AllocationAmount": "280.00000000"
                            }
                        ]
                    },
                    "Vendor": {
                        "VendorCode": null,
                        "VendorName": "Holiday Inn",
                        "VendorAddressName": null,
                        "AddressCode": null,
                        "Address1": null,
                        "Address2": null,
                        "Address3": null,
                        "City": null,
                        "State": null,
                        "PostalCode": null,
                        "CountryCode": null
                    }
                }
            ],
            "ID": null,
            "URI": null
        }
    ],
    "NextPage": null
}

JSON Example of an Unsuccessful Response


{
    "Error": {
        "Message": "Forbidden Request",
        "Server-Time": "2019-03-12T07:56:32",
        "Id": "65F68719-3FF5-459E-8B94-5FC93A5CD045"
    }
}

Update Invoices with a Calculated Tax Amount and Tax Rate

Updates invoices with calculated tax amount and tax rate.

Scopes

INVTV - Refer to Scope Usage for full details.

Request

URI

Template
https://{datacenterURI}//api/v3.0/invoice/salestaxvalidationrequest

Parameters

Name Type Format Description
invoice - body The tax information for the invoice that is to be updated.

Payload

Invoice

Response

Payload

Status Schema

Example

Request

{
  "CalculatedTaxAmount": "150.00",
  "CalculatedTaxRate": "0.40",
  "Comments": "Updating Calculated Tax",
  "LineItem": [
    {
      "CalculatedTaxAmount": "50.00",
      "CalculatedTaxRate": "0.05",
      "LineItemKey": "gWo0b$sLeIU2W18zqlQiELsE7TvQ"

    }
  ],

  "StatusCode": "CMPLT",
  "TaxReferenceID": "9A0F8C3EDF4040BBA94394A1A0CA6DCB"

}

Response

{
    "TaxReferenceID": "9A0F8C3EDF4040BBA94394A1A0CA6DCB",
    "Comments": null,
    "Status": "SUCCESS",
    "Type": null,
    "Code": 0,
    "Message": null,
    "Parameters": null,
    "RecordNumber": 0
}

JSON Example of an Unsuccessful Response

{
    "Message": " Status code is a required field. ERROR,CMPLT are valid values."
}

Invoices Schema

Sales Tax Validation v3 - Invoices

Name Type Format Description
Items array Invoice The result collection.
NextPage string - The URI of the next page of results, if any.
TotalCount Int32 - The amount of items returned.

Invoice

Name Type Format Description
BillToAddress object BillToAddress The billing address associated with the invoice.
CalculatedTaxAmount string - The calculated tax amount for the invoice.
CalculatedTaxRate string - The calculated tax rate for the invoice.
Comments string - Comments for the invoice.
CountryCode string - The country code for the line item.
CurrencyCode string - The 3-letter ISO 4217 currency code for the invoice currency. Example: USD, CAD
ID string - The unique identifier of the resource.
InvoiceAmount string - The invoice amount (the cost of the purchased items).
InvoiceDate string - The date of the invoice.
LineItem array LineItem The line items associated with the invoice.
OrgUnit1 through OrgUnit6 string - Not available for PUT. The code from the OrgUnit fields. These fields may not have data, depending on the configuration.
OrgUnit1Value though OrgUnit6Value string - Not available for PUT. The value from the OrgUnit fields. These fields may not have data, depending on the configuration.
Custom1 through Custom24 string - Not available for PUT. The code from the Custom fields. These fields may not have data, depending on the configuration.
Custom1Value through Custom24Value string - Not available for PUT. The value from the Custom fields. These fields may not have data, depending on the configuration.
PurchaseOrderNumber string - The purchase order number associated to the invoice.
RequestID string - The ID of the invoice.
ShippingAmount string - The shipping amount for the invoice.
ShipToAddress object ShipToAddress The shipping address associated with the invoice.
Status string - The status of the invoice.
StatusCode string - Required The status code for the invoice. Supported values: ERROR, CMPLT
Tax string - The tax, as shown on the invoice. This is the tax applied by the vendor.
TaxReferenceID string - Required The tax reference ID of the invoice.
Title string - The title of the invoice.
Total string - The total amount of the invoice.
URI string - The URI to the resource.
VendorInvoiceNumber string - The vendor invoice number that is associated with the invoice.

Sales Tax Validation v3 - BillToAddress

Name Type Format Description
Address1 string - Required Address line 1 of the billing address.
Address2 string - Address line 2 of the billing address.
Address3 string - Address line 3 of the billing address.
City string - Required The city of the billing address.
CountryCode string - Required The code of the country for the billing address.
ExternalID string - Required A unique value supplied by the customer to identify a particular billing address.
Name string - An optional name that can be given to the billing address.
PostalCode string - Required The postal code of the billing address.
State string - Required The state of the billing address.
StateProvince string - Required The province of the billing address.

Sales Tax Validation v3 - LineItem

Name Type Format Description
Allocations object Allocation The allocations associated with a line item.
CalculatedTaxAmount string - The calculated tax amount for the individual line item.
CalculatedTaxRate string - The calculated tax rate for the individual line item.
CommodityCode string - The commodity code that is tied to the expense type associated with the line item.
CountryCode string - The country code for the line item.
CurrencyCode string - The currency code for the individual line item.
LineItemKey string - Required A value that uniquely identifies the line item.
Quantity string - The quantity for the line item.
Total string - The total amount for the line item.
UnitPrice string - The unit price for the line item.
Vendor object InvoiceVendor Details about the vendor for each line item.

Sales Tax Validation v3 - Allocation

Name Type Format Description
AllocationAmount string - The allocation amount associated with the line item.
Custom1 through Custom20 string - Not available for PUT. The code from the Custom fields. These fields may not have data, depending on the configuration.
Custom1Value through Custom20Value string - Not available for PUT. The value from the Custom fields. These fields may not have data, depending on the configuration.

Sales Tax Validation v3 - Vendor

Name Type Format Description
Address1 string - Required Address line 1 of the vendor address.
Address2 string - Address line 2 of the vendor address.
Address3 string - Address line 3 of the vendor address.
City string - Required The city of the vendor address.
CountryCode string - Required The code of the country for the vendor address.
PostalCode string - Required The postal code of the vendor address.
State string - Required The state of the vendor address.
VendorAddressName string - Required The name for the vendor address.
VendorName string - Required The name of the vendor.
VendorCode string - Required The code associated with the vendor.

Sales Tax Validation v3 - ShipToAddress

Name Type Format Description
Address1 string - Required Address line 1 of the shipping address.
Address2 string - Address line 2 of the shipping address.
Address3 string - Address line 3 of the shipping address.
City string - Required The city of the shipping address.
CountryCode string - Required The code of the country for the shipping address.
ExternalID string - Required A unique value supplied by the customer to identify a particular shipping address.
Name string - An optional name that can be given to the shipping address.
PostalCode string - Required The postal code of the shipping address.
State string - Required The state of the shipping address.
StateProvince string - Required The province of the shipping address.

Status Schema

Name Type Format Description
Code int - Code of request result.
Comments string - Comments that are returned for the update request.
Message string - Message of request result.
RecordNumber int - Record number for the create/update request.
Status string - The status of the update. Supported values: SUCCESS, FAILURE
TaxReferenceID string - The tax reference ID of the updated invoice.
Type string - Type request result.

Vendor v3

The Vendor API allows you to develop processes that can be used to manage your Vendor collection for invoicing, adding new Vendors, updating, getting, or deleting information for existing Vendors.

Limitations: This API is only available to partners who have been granted access by SAP Concur. Access to this documentation does not provide access to the API. This API is not available in the China data center.

Vendor v3 - Products and Editions

Vendor v3 - Scope Usage

Name Description Endpoint
INVVEN Retrieves vendor information. GET

Vendor v3 - Dependencies

SAP Concur clients must purchase Concur Invoice in order to use this API.

Vendor v3 - Access Token Usage

This API supports both company level and user level access tokens.

Retrieve an Existing Vendor

Note: If authenticating with a Company access token the API will return all vendors associated with a specific entity.

GET /api/v3.0/invoice/vendors

Parameters

Name Type Format Description
limit Int32 query The maximum number of items to be returned in a response. The default is 25 and cannot exceed 1000.
offset string query Specifies the starting point for the next query when iterating through the collection response. Use with paged collections of resources.
sortDirection string query Ascending or descending, The default value will be ascending.
sortBy string query Field you need the results to be sorted by. Vendor Name will be made default if no value is sent. Only fields that are added to the vendor form can be used here. Fields have to be specified by name as specified in Doc.
searchType string query Applies for the entire given search parameters. The default value is exact. Supported values: exact, begins, contains, ends
vendorCode string query Vendor Code to be searched
vendorName string query Vendor Name to be searched
taxID string query Tax ID to be searched
buyerAccountNumber string query Buyer Account Number to be searched
paymentMethodType string query Payment Method Type - valid values are ACH, CARD, CHECK, CLIENT, PAYPVD, VCHER, WIRE
addressCode string query Address Code to be searched
address1 string query Address 1 to be searched
address2 string query Address 2 to be searched
address3 string query Address 3 to be searched
city string query City to be searched
state string query State to be searched
postalCode string query Postal Code to be searched
approved string query Find Approved/Unapproved Vendors, True/False
country string query Country to be searched
custom1 string query Custom 1 to be searched
custom2 string query Custom 2 to be searched
custom3 string query Custom 3 to be searched
custom4 string query Custom 4 to be searched
custom5 string query Custom 5 to be searched
custom6 string query Custom 6 to be searched
custom7 string query Custom 7 to be searched
custom8 string query Custom 8 to be searched
custom9 string query Custom 9 to be searched
custom10 string query Custom 10 to be searched
custom11 string query Custom 11 to be searched
custom12 string query Custom 12 to be searched
custom13 string query Custom 13 to be searched
custom14 string query Custom 14 to be searched
custom15 string query Custom 15 to be searched
custom16 string query Custom 16 to be searched
custom17 string query Custom 17 to be searched
custom18 string query Custom 18 to be searched
custom19 string query Custom 19 to be searched
custom20 string query Custom 20 to be searched

Input

None.

Response

Vendors Schema

Create Vendors

POST /api/v3.0/invoice/vendors Note: If authenticating with a Company access token, the API will create the requested Vendors.

Parameters

Name Type Format Description
vendors - body The vendor details.

Input

Vendors Schema

Response

Vendors Schema

Update Existing Vendors

PUT /api/v3.0/invoice/vendors Note: If authenticating with a Company access token, the API will update the requested Vendors.

Parameters

Name Type Format Description
vendors - body The vendor details.

Input

Vendors Schema

Response

Vendors Schema

Delete Vendor

DELETE /api/v3.0/invoice/vendors Note: If authenticating with a Company access token, the API will delete the requested Vendor.

Parameters

Name Type Format Description
vendorCode string query Required Vendor Code to be deleted
addressCode string query Required Address Code to be deleted

Input

None.

Response

Vendors Schema

Add/Update Vendor Banking

PUT /api/v3.0/invoice/vendor/banks Note: If authenticating with a Company access token, the API will create / update the requested Vendor Banking info.

Parameters

Name Type Format Description
vendorBanks - body The vendor banking info

Input

Vendor Bank Schema

Response

Vendor Bank Schema

Add Vendor Group

PUT /api/v3.0/invoice/vendor/groups Note: If authenticating with a Company access token, the API will create the requested Vendor groups.

Parameters

Name Type Format Description
vendorCode string query Required The vendor code of the vendor to update
addressCode string query Requred The address code of the vendor to update
vendorGroups - body The vendor group details

Input

Vendor Group Schema

Response

Vendor Group Schema

Delete Vendor Group

DELETE /api/v3.0/invoice/vendor/groups Note: If authenticating with a Company access token, the API will delete the requested Vendor group.

Parameters

Name Type Format Description
vendorCode string query Required The vendor code of the vendor to update
addressCode string query Requred The address code of the vendor to update
groupName string query Requred The group name to be deleted

Input

None.

Response

Vendor Group Schema

Vendor v3 - Schema

Vendors

Name Type Format Description
Items array Vendor The result collection.
NextPage string - The URI of the next page of results, if any.
RequestRunSummary string - -
TotalCount Int - -
Vendor array Vendor Required Vendor

Vendor

Name Type Format Description
AccountNumber string - The Buyer Account Number.
Address1 string - The Vendor Address 1.
Address2 string - The Vendor Address 2.
Address3 string - The Vendor Address 3.
AddressCode string - Required The Address Code.
AddressImportSyncID string - This ID is originally generated by Invoice when an employee requests a new vendor. The Employee Request Vendor Extract provides this value to positively identify the vendor address record when reimporting vendor from the client's system of record for the Vendor Master List.
Approved string - Vendor Approval Status.
City string - The Vendor City.
ContactEmail string - The Vendor Contact Email.
ContactFirstName string - The Vendor Contact First Name.
ContactLastName string - The Vendor Contact Last Name.
ContactPhoneNumber string - The Vendor Contact Phone Number.
Country string - The Vendor Country.
CountryCode string - The Vendor Country Code.
CurrencyCode string - The Vendor Currency Code.
Custom1 string - A value that can be applied to a custom field 1 that is part of the vendor form.
Custom10 string - A value that can be applied to a custom field 10 that is part of the vendor form.
Custom11 string - A value that can be applied to a custom field 11 that is part of the vendor form.
Custom12 string - A value that can be applied to a custom field 12 that is part of the vendor form.
Custom13 string - A value that can be applied to a custom field 13 that is part of the vendor form.
Custom14 string - A value that can be applied to a custom field 14 that is part of the vendor form.
Custom15 string - A value that can be applied to a custom field 15 that is part of the vendor form.
Custom16 string - A value that can be applied to a custom field 16 that is part of the vendor form.
Custom17 string - A value that can be applied to a custom field 17 that is part of the vendor form.
Custom18 string - A value that can be applied to a custom field 18 that is part of the vendor form.
Custom19 string - A value that can be applied to a custom field 19 that is part of the vendor form.
Custom2 string - A value that can be applied to a custom field 2 that is part of the vendor form.
Custom20 string - A value that can be applied to a custom field 20 that is part of the vendor form.
Custom3 string - A value that can be applied to a custom field 3 that is part of the vendor form.
Custom4 string - A value that can be applied to a custom field 4 that is part of the vendor form.
Custom5 string - A value that can be applied to a custom field 5 that is part of the vendor form.
Custom6 string - A value that can be applied to a custom field 6 that is part of the vendor form.
Custom7 string - A value that can be applied to a custom field 7 that is part of the vendor form.
Custom8 string - A value that can be applied to a custom field 8 that is part of the vendor form.
Custom9 string - A value that can be applied to a custom field 9 that is part of the vendor form.
DefaultEmployeeID string - The Default Employee ID of the employee connected to the vendor.
DefaultExpenseTypeName string - The Default Expense Type tied to the vendor.
DiscountPercentage string - The Discount Percentage.
DiscountTermsDays string - The Vendor Discount Terms Days.
ID string - The unique identifier of the resource.
IsLineItemVatIncld string - Line item Unit Price Contains VAT ,
IsVisibleForContentExtraction string - Flag that indicates if the vendor will be available for OCR within Brainware
PaymentMethodType string - Preferred Payment Type for Vendor.
PaymentTerms Integer between 1 and 999 - The Vendor Payment Terms. This field represents the number of days by which a payment must be made, for example, 30 days
PostalCode string - The Vendor Postal Code / Zip.
ProvincialTaxID string - The Vendor Provincial Tax ID. Note that this value is not encrypted at REST.
PurchaseOrderContactEmail string - The Purchase Order Contact Email.
PurchaseOrderContactFirstName string - The Purchase Order Contact First Name.
PurchaseOrderContactLastName string - The Purchase Order Contact Last Name.
PurchaseOrderContactPhoneNumber string - The Purchase Order Contact Phone Number.
ShippingMethod string - The Vendor Shipping Method.
ShippingTerms string - The Vendor Shipping Terms.
State string - The Vendor State.
StatusList array Status Required Status results
TaxID string - The Vendor Tax ID. Note that this value is not encrypted at REST.
TaxType string - The Vendor Tax Type.
URI string - The URI to the resource.
VendorBankList array VendorBank The list of a vendor's active banking information. Read-Only
VendorCode string - Required The vendor code of the request.
VendorFormName string - The vendor form name this vendor is associated with.
VendorGroupList array - The list of vendor groups by name. Read-Only
VendorName string - The name of the vendor.
VoucherNotes string - Notes sent to Vendor along with authorization to charge Card Voucher.

Vendor Banking Input/Response Schema

Name Type Format Description
Items array VendorBank The result collection.
NextPage string - The URI of the next page of results, if any.
RequestRunSummary string - -
TotalCount Int - -
VendorBank array VendorBank Required Vendor Banking Info

VendorBank

Name Type Format Description
AccountNumber string - Required The account number.
AccountType enum - Required The account type--CHCK for Checking, SAVE for Savings.
AddressCode string - Required The Address Code.
BankCode string - Bank Code
BankName string - The bank name.
BranchCode string - Branch Code
BranchLocation string - The branch location
CountryCode string - The country code.
CurrencyAlphaCode string - The currency alpha Code.
ID string - The unique idenitifier of this resource.
IsActive string - Required Is information active
NameOnAccount string - Required The name on the account.
RoutingNumber string - The routing number.
StatusList array status Status results
TransType string - The trans type.
URI string - The URI to the resource.
VendorCode string - Required The vendor code of the request.

Vendor Group Input/Response Schema

Name Type Format Description
Items array VendorGroup The result collection.
NextPage string - The URI of the next page of results, if any.
RequestRunSummary string - -
TotalCount Int - -
VendorGroup array VendorGroup Required Vendor Group List

VendorGroup

Name Type Format Description
ID string - The unique identifier of the resource.
Name string - Required The vendor group name.
StatusList array status Status results.
URI string - The URI to the resource.

Status

Name Type Format Description
Code int - Code of request result
Message string - Message of request result
RecordNumber int - Record Number for create/update request.
Type string - Type request result

Receipts

Get Started - Receipts v4

Receipts v4 - Overview

The Receipts V4 API accepts three different formulae for posting a receipt:

  1. Receipt Data - Your receipt data is stored along with an automatically generated receipt image file.
  2. Receipt Data & Receipt Image - Your receipt data and receipt image file are stored.
  3. Receipt Image w/o Data - Your receipt image file is stored along with some accompanying metadata.

All of the above are receipt resources, but the service draws a distinction between resources with data versus resources that are standalone images.

Resources with data are schema-enforced and are referred to as e-receipts.

Resources of standalone images are referred to as as Image-Only Receipts.

These two different resources are sent/fetched from the Receipts V4 API via different endpoints: * E-Receipts (Receipts With Data) - Use E-Receipt Endpoints * Image-Only Receipts (Standalone Images Without Data) - Use Image-Only Receipt Endpoints

Note: The Receipts V4 API only provides GET access to individual or user’s receipts that have been submitted through this API, and, therefore the response will not be comprehensive of every user receipt within SAP Concur. All other images should be obtained via the Image v1 API. Additionally, only the receipts will be returned, there will not be any corresponding entry data. Examples of Enterprise apps that should use the Image v1 API include: ERP integrations for financial journal entry postings, VAT reclaim integrations that obtain transactions to calculate VAT reclaim, project billing integrations used to substantiate expenses billed back, etc.

Receipts - Prior Versions

Get Started - Receipts v4 - Overview of Version 4.0

Version 4.0 of the Receipts API offers features like more receipt types, automatic e-receipt generation in end user’s preferred language and ability for partners to provide detailed tax information. Unlike version 3.0, we are discontinuing the use of matching facts; instead the partner will have to create a receipt for a specific end user. Receipts 4.0 works only with the new Authentication API.

Regional Availability

https://us.api.concursolutions.com/receipts/
https://emea.api.concursolutions.com/receipts/

Explore the API

Prerequisites

  1. Create a sandbox if you don't already have one.
  2. Read the Getting Started section of Authentication API.

Once you have registered your application, read about the API endpoints, or click the button to download a request collection for Postman.

Run in Postman

Receipts v4 - Retrieve a User Access Token

Before making requests to the Receipts API, you must obtain an access token from the Authentication API.

The response will include an access_token field, which contains your access token. For subsequent calls, you will need to include this access token in the Authorization header of your calls. An id_token will be also included in the response. In order to retrieve the unique ID for your user, you will have to decode this id_token at jwt.io. You will need this ID in order to post receipts.

Examples:

cURL:

curl -d "client_secret={YOUR SECRET}&client_id={YOUR CLIENT ID}&grant_type=password&username={YOUR USERNAME}&password={YOUR PASSWORD}" https://us.api.concursolutions.com/oauth2/v0/token

HTTPie:

http -f POST https://us.api.concursolutions.com/oauth2/v0/token client_secret={YOUR SECRET} client_id={YOUR CLIENT ID} grant_type=password username={YOUR USERNAME} password=P{YOUR PASSWORD}

Explore the API in JavaScript

Below are some simple NodeJS code snippets for getting a token and posting a receipt.

Retrieve a User Access Token:

'use strict';
const request = require('request');

request.post({
    url:'https://us.api.concursolutions.com/oauth2/v0/token',
    form: {
        client_secret: 'YOUR VALUE HERE',
        client_id: 'YOUR VALUE HERE',
        username: 'YOUR VALUE HERE',
        password: 'YOUR VALUE HERE',
        grant_type: 'password'
    }},
    (err, httpResponse, body) => {
        if(err) { console.log(err); }
        console.log('Status:', httpResponse.statusCode);
        console.log('Response:', body);
    });

Post a Receipt

'use strict';
const https = require('https');

const ACCESS_TOKEN = 'YOUR ACCESS TOKEN HERE';
const USER_ID = 'YOUR VALUE HERE';
const receipt = JSON.stringify(YOUR_RECEIPT_HERE);

const options = {
    hostname: 'us.api.concursolutions.com',
    path: `/receipts/v4/users/${USER_ID}`,
    method: 'POST',
    headers: {
        'Authorization': `Bearer ${ACCESS_TOKEN}`,
        'Content-Type': 'application/json',
        'Content-Length': Buffer.byteLength(receipt),
        'Link': '<http://schema.concursolutions.com/general-receipt.schema.json>;rel=describedBy'
    }
};

const req = https.request(options, (res) => {
    console.log('statusCode:', res.statusCode);
    console.log('headers:', res.headers);

    res.on('data', (data) => {
        process.stdout.write(data);
    });
});

req.write(receipt);
req.end();

req.on('error', (e) => {
    console.error(e);
});

Endpoints

Definitions of Resources

Note: The Receipts V4 API only provides GET access to individual or user’s receipts that have been submitted through this API, and, therefore the response will not be comprehensive of every user receipt within SAP Concur. All other images should be obtained via the Image v1 API. Additionally, only the receipts will be returned, there will not be any corresponding entry data. Examples of Enterprise apps that should use the Image v1 API include: ERP integrations for financial journal entry postings, VAT reclaim integrations that obtain transactions to calculate VAT reclaim, project billing integrations used to substantiate expenses billed back, etc.

Supported Image Formats

Endpoints - General

Endpoint Response Format Request Summary
GET / JSON Get service index URLs
GET /v4/status/:receiptId JSON Get the status of a receipt

Endpoint: Service Index

GET /

Making a GET request to the root of the service will return a list of current endpoints. If endpoint URLs ever change, the service index will be updated. To ensure that you are using the correct URLs, the safest practice is to check the service index before every request. The response will include current URLs for all endpoints in the receipt service.

Example Requests:

cURL:

curl -H "Authorization: Bearer {YOUR ACCESS TOKEN}" https://us.api.concursolutions.com/receipts/

HTTPie:

http https://us.api.concursolutions.com/receipts/ 'Authorization:Bearer {YOUR ACCESS TOKEN}'

Example Response:

{
  "links": [
    {
      "rel": "self",
      "href": "https://us.api.concursolutions.com/receipts/v4"
    },
    {
      "rel": "receipt-get",
      "method": "GET",
      "href": "https://us.api.concursolutions.com/receipts/v4/{receiptId}"
    },
    {
      "rel": "receipt-post",
      "method": "POST",
      "href": "https://us.api.concursolutions.com/receipts/v4/users/{userId}"
    },
    {
      "rel": "receipts-get-user",
      "method": "GET",
      "href": "https://us.api.concursolutions.com/receipts/v4/users/{userId}"
    },
    {
      "rel": "schemas-get",
      "method": "GET",
      "href": "https://us.api.concursolutions.com/receipts/schemas"
    }
  ]
}

Back to Top

E-Receipts

Endpoint Response Format Request Summary
GET /schemas JSON Get currently supported receipt schemas
POST /v4/users/:userId N/A Post a receipt
GET /v4/users/:userId JSON Get a user's receipts
GET /v4/:receiptId JSON Get a receipt by ID
GET /v4/:receiptId/image image file Get a receipt image.

Endpoint: Schemas

GET /schemas/:schemaId

Parameter Requirement Value
schemaId optional The ID of the schema to be returned.

The response to a GET request to /schemas will have a list of JSON validation schemas for available receipt types. An array of supportingSchemas is also returned, but these do not represent actual receipt types.

If a schema ID is provided, then only the schema with that ID will be returned, instead of the entire schema index. The ID's of schemas are not UUIDs, but are instead just the names of the schema with the extension .schema.json. For example, car-rental-receipt.schema.json or air-receipt.schema.json.

One of the receipt schemas must be included in the link header of receipt POST requests with the relationship of describedBy. This looks like link: <http://schema.concursolutions.com/{RECEIPT TYPE}.schema.json>;rel=describedBy.

Example Requests:

cURL for the schema index:

curl -H "Authorization: Bearer {YOUR ACCESS TOKEN}" https://us.api.concursolutions.com/receipts/schemas/

HTTPie for the schema index:

http https://us.api.concursolutions.com/receipts/schemas 'Authorization:Bearer {YOUR ACCESS TOKEN}'

cURL for a single schema:

curl -H "Authorization: Bearer {YOUR ACCESS TOKEN}" https://us.api.concursolutions.com/receipts/schemas/car-rental-receipt.schema.json

HTTPie for a single schema:

http https://us.api.concursolutions.com/receipts/schemas/car-rental-receipt.schema.json 'Authorization:Bearer {YOUR ACCESS TOKEN}'

Example Response:

{
  "receiptSchemas": [
    {
      "rel": "http://schema.concursolutions.com/air-receipt.schema.json",
      "method": "GET",
      "href": "https://us.api.concursolutions.com/receipts/schemas/air-receipt.schema.json"
    },
    {
      "rel": "http://schema.concursolutions.com/car-rental-receipt.schema.json",
      "method": "GET",
      "href": "https://us.api.concursolutions.com/receipts/schemas/car-rental-receipt.schema.json"
    },
    {
      "rel": "http://schema.concursolutions.com/general-receipt.schema.json",
      "method": "GET",
      "href": "https://us.api.concursolutions.com/receipts/schemas/general-receipt.schema.json"
    },
    {
      "rel": "http://schema.concursolutions.com/ground-transport-receipt.schema.json",
      "method": "GET",
      "href": "https://us.api.concursolutions.com/receipts/schemas/ground-transport-receipt.schema.json"
    },
    {
      "rel": "http://schema.concursolutions.com/hotel-receipt.schema.json",
      "method": "GET",
      "href": "https://us.api.concursolutions.com/receipts/schemas/hotel-receipt.schema.json"
    },
    {
      "rel": "http://schema.concursolutions.com/jpt-ic-card-receipt.schema.json",
      "method": "GET",
      "href": "https://us.api.concursolutions.com/receipts/schemas/jpt-ic-card-receipt.schema.json"
    },
    {
      "rel": "http://schema.concursolutions.com/rail-receipt.schema.json",
      "method": "GET",
      "href": "https://us.api.concursolutions.com/receipts/schemas/rail-receipt.schema.json"
    }
  ],
  "supportingSchemas": [
    {
      "rel": "http://schema.concursolutions.com/address-original.schema.json",
      "method": "GET",
      "href": "https://us.api.concursolutions.com/receipts/schemas/address-original.schema.json"
    },
    {
      "rel": "http://schema.concursolutions.com/address.schema.json",
      "method": "GET",
      "href": "https://us.api.concursolutions.com/receipts/schemas/address.schema.json"
    },
    {
      "rel": "http://schema.concursolutions.com/common.schema.json",
      "method": "GET",
      "href": "https://us.api.concursolutions.com/receipts/schemas/common.schema.json"
    },
    {
      "rel": "http://schema.concursolutions.com/discount.schema.json",
      "method": "GET",
      "href": "https://us.api.concursolutions.com/receipts/schemas/discount.schema.json"
    },
    {
      "rel": "http://schema.concursolutions.com/line-item.schema.json",
      "method": "GET",
      "href": "https://us.api.concursolutions.com/receipts/schemas/line-item.schema.json"
    },
    {
      "rel": "http://schema.concursolutions.com/location.schema.json",
      "method": "GET",
      "href": "https://us.api.concursolutions.com/receipts/schemas/location.schema.json"
    },
    {
      "rel": "http://schema.concursolutions.com/merchant.schema.json",
      "method": "GET",
      "href": "https://us.api.concursolutions.com/receipts/schemas/merchant.schema.json"
    },
    {
      "rel": "http://schema.concursolutions.com/payments.schema.json",
      "method": "GET",
      "href": "https://us.api.concursolutions.com/receipts/schemas/payments.schema.json"
    },
    {
      "rel": "http://schema.concursolutions.com/receipt-core.schema.json",
      "method": "GET",
      "href": "https://us.api.concursolutions.com/receipts/schemas/receipt-core.schema.json"
    },
    {
      "rel": "http://schema.concursolutions.com/taxes.schema.json",
      "method": "GET",
      "href": "https://us.api.concursolutions.com/receipts/schemas/taxes.schema.json"
    }
  ]
}

Back to Top

Endpoint: Get Receipt Status

GET /v4/status/:receiptId

Parameter Requirement Value
receiptId required The id of the receipt associated with the image.

This endpoint may be used to see the current processing status of a receipt.

When a successful POST request is made the Link header of the response contains a 'processing-status' URL. This processing-status URL will be available for two weeks after the initial POST and will provide information regarding the processing status of your receipt.

There are four possible top level statuses: ACCEPTED, FAILED, PROCESSING, and PROCESSED.

In additional to a high level status, information will be provided in an array of event logs. Events that may be included in the logs will be typed as INFO, DEBUG, WARNING, or ERROR.

Example event messages:

Type Message
INFO Receipt accepted. Queued for processing.
INFO Initiated receipt processing. (event for each attempt)
ERROR Error from User Profile service. Queued for reprocessing.
ERROR Error from Imaging service. Queued for reprocessing.
ERROR Error during image generation or retrieval. Queued for reprocessing.
INFO Receipt image generated.
ERROR Processing failed.
INFO Processing finished.

Example Requests:

cURL:

curl -H "Authorization: Bearer {YOUR ACCESS TOKEN}" https://us.api.concursolutions.com/receipts/v4/status/{RECEIPT ID}

HTTPie:

http https://us.api.concursolutions.com/receipts/v4/status/{RECEIPT ID} "Authorization: Bearer {YOUR ACCESS TOKEN}"

Example Response:

{
  "status": "PROCESSED",
  "logs": [
    {
      "logLevel": "INFO",
      "message": "Receipt accepted. Queued for processing.",
      "timestamp": "Mon, 08 May 2017 23:05:52 GMT"
    },
    {
      "logLevel": "INFO",
      "message": "Initiated receipt processing.",
      "timestamp": "Mon, 08 May 2017 23:05:52 GMT"
    },
    {
      "logLevel": "INFO",
      "message": "Receipt image generated.",
      "timestamp": "Mon, 08 May 2017 23:05:53 GMT"
    },
    {
      "logLevel": "INFO",
      "message": "Processing finished.",
      "timestamp": "Mon, 08 May 2017 23:05:54 GMT"
    }
  ]
}

Back to Top

Endpoint: Post a Receipt

POST /v4/users/:userId

Parameter Requirement Value
userId required The id of the user to whom the receipt belongs.
receipt required The JSON receipt to be posted.
image optional Image of the receipt. If an image isn't provided, one will be generated automatically from the JSON. Refer to Supported Image Formats for more information.

Creating a receipt requires JSON data about the transaction and, optionally, an image of the receipt. If an image is not supplied with the request, SAP Concur will automatically generate a receipt image based on the data provided. JSON schemas are used to validate the format of receipt data received in POST requests.

Successful POST requests will receive a response of 201 Created. The Location header of the response contains a URL for your receipt. Once the receipt has been processed, it can be retrieved at this URL. The Link header of the response contains a processing-status URL for your receipt. More information can be found here.

Helpful Notes: - Include link as a header and make its value: “;rel=describedBy” - Copy a sample receipt of that receipt type from the documentation (https://developer.concur.com/api-reference/receipts/sample-receipts.html) and post it into the body of this POST call → you can then edit this body to your specification

If you are not providing an image with your receipt data, the body of the request should be your receipt JSON.

Receipt images may be posted along with data. In this case, SAP Concur will use the provided image instead of generating a new one. To post data and an image, use multipart form data. The Content-Type:multipart/form-data header must be set. The image should be included under the key image, and the receipt JSON should be included under the key receipt. For information regarding image size, dimension, and type, please refer to Supported Image Formats.

Example Requests:

cURL data without image:

curl -v -X POST https://us.api.concursolutions.com/receipts/v4/users/{USER ID FROM YOUR ID TOKEN} \
-H "Authorization: Bearer {YOUR ACCESS TOKEN}" \
-H "Content-Type: application/json" \
-H "link: <http://schema.concursolutions.com/{VALIDATION SCHEMA FROM SCHEMA ENDPOINT}.schema.json>;rel=describedBy" \
-d @{PATH TO YOUR RECEIPT JSON}

cURL data and image:

curl -v -k -X POST https://us.api.concursolutions.com/receipts/v4/users/{USER ID FROM YOUR ID TOKEN} \
-H "Authorization: Bearer {YOUR ACCESS TOKEN}" \
-H "Content-Type:multipart/form-data" \
-H "link: <http://schema.concursolutions.com/{VALIDATION SCHEMA FROM SCHEMA ENDPOINT}.schema.json>;rel=describedBy" \
-F "receipt=<{PATH TO YOUR RECEIPT JSON};type=application/json" \
-F "image=@{PATH TO YOUR IMAGE};type={FILE MIME TYPE OF YOUR IMAGE}"

HTTPie data without image:

http POST https://us.api.concursolutions.com/receipts/v4/users/{USER ID FROM YOUR ID TOKEN} \
"Authorization:Bearer {YOUR ACCESS TOKEN}" \
"Content-Type: application/json" \
"link: <http://schema.concursolutions.com/{VALIDATION SCHEMA FROM SCHEMA ENDPOINT}.schema.json>;rel=describedBy" \
< {PATH TO YOUR RECEIPT JSON}

Example Response:

HTTP/1.1 201 Created
Link: <http://schema.concursolutions.com/car-rental-receipt.schema.json>; rel="describedBy", <https://us.api.concursolutions.com/receipts/v4/status/b0a4ab2bce8a49a08cf177cb997bf2ee>; rel="processing-status"
Location: https://us.api.concursolutions.com/receipts/v4/b0a4ab2bce8a49a08cf177cb997bf2ee
Content-Length: 0
Connection: keep-alive

Back to Top

Endpoint: Get a Receipt by ID

GET /v4/:receiptId

Parameter Requirement Value
receiptId required The id of the receipt to be returned.

Returns the JSON receipt associated with the ID in the URL.

Example Requests:

cURL:

curl -H "Authorization: Bearer {YOUR ACCESS TOKEN}" https://us.api.concursolutions.com/receipts/v4/{RECEIPT ID}

HTTPie:

http https://us.api.concursolutions.com/receipts/v4/{RECEIPT ID} "Authorization: Bearer {YOUR ACCESS TOKEN}"

Example Response

{
  "dateTimeReceived": "2016-09-28T21:41:21.087Z",
  "id": "85b76a2bf51a4ed7b8b252994d7d9e2b",
  "image": "",
  "receipt": {
    ...Receipt JSON...
  },
  "userId": "08bdda1e-0d4f-4261-9f1b-f9b8d9f817d6",
  "validationSchema": "http://schema.concursolutions.com/car-rental-receipt.schema.json",
  "self": "https://us.api.concursolutions.com/receipts/v4/85b76a2bf51a4ed7b8b252994d7d9e2b",
  "template": "https://us.api.concursolutions.com/receipts/v4/{receiptId}"
}

Back to Top

Endpoint: Get Receipts By UserId

GET /v4/users/:userId

Parameter Requirement Value
userId required The id of the user whose receipts will be returned.

Returns all receipts for a given user ID.

Example Requests:

cURL:

curl -H "Authorization: Bearer {YOUR ACCESS TOKEN}" https://us.api.concursolutions.com/receipts/v4/users/{USER ID}

HTTPie:

http https://us.api.concursolutions.com/receipts/v4/users/{USER ID} "Authorization: Bearer {YOUR ACCESS TOKEN}"

Example Response:

{
  "receipts": [
    {
      "dateTimeReceived": "2016-09-28T21:41:21.087Z",
      "id": "85b76a2bf51a4ed7b8b252994d7d9e2b",
      "image": "",
      "receipt": {
        ...Receipt JSON...
      },
      "userId": "08bdda1e-0d4f-4261-9f1b-f9b8d9f817d6",
      "validationSchema": "http://schema.concursolutions.com/car-rental-receipt.schema.json",
      "self": "https://us.api.concursolutions.com/receipts/v4/85b76a2bf51a4ed7b8b252994d7d9e2b",
      "template": "https://us.api.concursolutions.com/receipts/v4/{receiptId}"
    },
    {
      "dateTimeReceived": "2016-09-28T19:59:30.488Z",
      "id": "df8c1161d917439c9e6f141fd0d6b588",
      "image": "",
      "receipt": {
        ...Receipt JSON...
      },
      "userId": "08bdda1e-0d4f-4261-9f1b-f9b8d9f817d6",
      "validationSchema": "http://schema.concursolutions.com/car-rental-receipt.schema.json",
      "self": "https://us.api.concursolutions.com/receipts/v4/df8c1161d917439c9e6f141fd0d6b588",
      "template": "https://us.api.concursolutions.com/receipts/v4/{receiptId}"
    },
    ...
  ]
}

Back to Top

Endpoint: Get Receipt Image

GET /v4/:receiptId/image

Parameter Requirement Value
receiptId required The id of the receipt associated with the image.

If an image or PDF document was generated by or POSTed to Receipts v4, this endpoint can return the image in the same format that it was originally received by the API. Images for receipts created with v3 of the API are not accessible via this endpoint.

Example Requests:

cURL:

curl -H "Authorization: Bearer {YOUR ACCESS TOKEN}" https://us.api.concursolutions.com/receipts/v4/{RECEIPT ID}/image

HTTPie:

http https://us.api.concursolutions.com/receipts/v4/{RECEIPT ID}/image "Authorization: Bearer {YOUR ACCESS TOKEN}"

Back to Top

Image-Only Receipts

Note: This API is not designed to obtain the receipt images attached to an expense report. If you are an Enterprise Partner creating integrations that are intended to obtain final-approved Expense or Invoice data, and the accompanying receipt images that substantiate those transactions you will need to use Image v1. These scenarios include, but are not limited to: ERP integrations for financial journal entry postings, VAT reclaim integrations that obtain transactions to calculate VAT reclaim, project billing integrations used to substantiate expenses billed back, etc.

Endpoint Response Format Request Summary
POST /v4/users/:userId/image-only-receipts N/A Post an image-only receipt
GET /v4/users/:userId/image-only-receipts JSON Get a user's image-only receipts
GET /v4/image-only-receipts/:receiptId JSON Get an image-only receipt by ID

Endpoint: Post an Image-Only Receipt

POST /v4/users/:userId/image-only-receipts

Parameter Requirement Value
userId required The id of the user to whom the receipt image belongs.
image required Image of the receipt. Refer to Supported Image Formats for more information.

Successful POST requests will receive a response of 202 Accepted. The Location header of the response contains a URL for your receipt image. Once the receipt has been processed, it can be retrieved at this URL. The Link header of the response contains a processing-status URL for your receipt image.

Helpful Notes: - The header must include content-type with multipart/form-data as its value - In the body, add "image" as a key and select "file" from the dropdown since you will be linking an image file. Then, choose your saved image file as the value.

For information regarding image size, dimension, and type, please refer to Supported Image Formats.

Example Requests:

cURL:

curl -v -X POST https://us.api.concursolutions.com/receipts/v4/users/{USER ID FROM YOUR ID TOKEN}/image-only-receipts \
-H "Authorization: Bearer {YOUR ACCESS TOKEN}" \
-H "Content-Type:multipart/form-data" \
-F "image=@{PATH TO YOUR IMAGE};type=image/{FILE MIME TYPE OF YOUR IMAGE}"

Example Response:

HTTP/1.1 202 Accepted
Link: <https://us.api.concursolutions.com/receipts/v4/status/b0a4ab2bce8a49a08cf177cb997bf2ee>; rel="processing-status"
Location: https://us.api.concursolutions.com/receipts/v4/images/b0a4ab2bce8a49a08cf177cb997bf2ee
Content-Length: 0
Connection: keep-alive

Back to Top

Endpoint: Get Image-Only Receipts By UserId

GET /v4/users/:userId/image-only-receipts

Parameter Requirement Value
userId required The id of the user whose receipt images will be returned.

Returns the JSON metadata of receipt images for the user ID specified in the URL. Results should be paginated in the same manner as the e-receipt endpoint.

Example Requests:

cURL:

curl -H "Authorization: Bearer {YOUR ACCESS TOKEN}" https://us.api.concursolutions.com/receipts/v4/users/{USER ID}/image-only-receipts

HTTPie:

http https://us.api.concursolutions.com/receipts/v4/users/{USER ID}/image-only-receipts "Authorization: Bearer {YOUR ACCESS TOKEN}"

Example Response:

HTTP/1.1 200 OK
Content-Length: 800
Connection: keep-alive

{
    "receiptsImages": [
        {
            "dateTimeReceived": "Wed May 24 2017 16:14:17 GMT+00:00",
            "id": "a90fc48e0f0a44f2bd4838fd773b07a5",
            "image": "https://us.api.concursolutions.com/receipts/v4/image-only-receipts/a90fc48e0f0a44f2bd4838fd773b07a5/image",
            "userId": "abcd123456efg"
        },
        { ... },
    ],
    "next": "https://us.api.concursolutions.com/receipts/v4/users/abcd123456efg/image-only-receipts/page/1507587575592_d4721b2f3b304a9a9325fabdad5f50ad"
}

Back to Top

Endpoint: Get an Image-Only Receipt by ID

GET /v4/image-only-receipts/:receiptId

Parameter Requirement Value
receiptId required The id of the receipt image to be returned.

Returns the JSON metadata associated with the ID in the URL.

Example Requests:

cURL:

curl -v -X GET https://us.api.concursolutions.com/receipts/v4/image-only-receipts/{RECEIPT ID} \
-H "Authorization: Bearer {YOUR ACCESS TOKEN}"

HTTPie:

http https://us.api.concursolutions.com/receipts/v4/image-only-receipts/{RECEIPT ID} "Authorization: Bearer {YOUR ACCESS TOKEN}"

Example Response

HTTP/1.1 200 OK
Content-Length: 272
Connection: keep-alive

{
    "dateTimeReceived": "Wed May 24 2017 16:14:17 GMT+00:00",
    "id": "a90fc48e0f0a44f2bd4838fd773b07a5",
    "image": "https://us.api.concursolutions.com/receipts/v4/image-only-receipts/a90fc48e0f0a44f2bd4838fd773b07a5/image",
    "userId": "abcd123456efg"
}

Back to Top

Endpoint: Get Receipt Image (Image-Only)

GET /v4/image-only-receipts/:receiptId/image

Parameter Requirement Value
receiptId required The id of the receipt image to be returned.

Returns the image in the same format that it was originally received by the API (image/png, image/jpg, image/jpeg, image/tiff, image/tif, image/gif, or application/pdf).

Example Requests:

cURL:

curl -H "Authorization: Bearer {YOUR ACCESS TOKEN}" https://us.api.concursolutions.com/receipts/v4/image-only-receipts/{RECEIPT ID}/image

HTTPie:

http https://us.api.concursolutions.com/receipts/v4/image-only-receipts/{RECEIPT ID}/image "Authorization: Bearer {YOUR ACCESS TOKEN}"

Back to Top

Supported Receipt Types

Receipts can be any of the following types

See the schema documentation below for the specifications of each type, plus the various schemas that are shared components of each receipt schema. Property names mentioned in bold italics are required fields.

Schemas

Address

Property Name Type Format Description
streetAddress string N/A
addressLocality string N/A City
addressRegion string ^[a-zA-Z0-9]{1,3}$ 1 to 3 character country subdivision code as defined in ISO 3166-2:2013
addressCountry string country-code 2 or 3 character country code as defined in ISO 3166-1:2013
postalCode string N/A

Air Receipt

Schema for airline receipts. * Includes all of Receipt Core Definitions

Property Name Type Format Description
itineraryLocator string ^(?!\s*$).+ Unique ID of an itinerary (also know as a trip) in Concur’s Itinerary Service. An itinerary can contain one or more bookings from various sources.
tickets array tickets Air tickets issued.
lineItems array lineItems Ancillary airline fees.

tickets

Property Name Type Format Description
number string N/A Ticket number issued by the airline when the payment is made. Ticket numbers are globally unique for all IATA carriers. The first 3 digits identify the airline. The three digit code for each airline can be found here. For example the ticket number for American Airlines where 001 is the airline: 0012375432602.
recordLocator string N/A Confirmation identifier for the ticket created by the airline. For most airlines this is a 6 character alphanumeric code that is unique for a short period of time and could be reused in the future.
issueDateTime string date-time Date and time the ticket was issued.
pseudoCityCode string ^[a-zA-Z]{3}$ IATA city code the ticket was issued from. For example, SEA for Seattle.
IATAAgencyNumber string ^[0-9]{8}$ Identifying number assigned by the IATA to the agency issuing the ticket.
agencyName string N/A Name of the agency issuing the ticket.
passengerName string N/A Name of the passenger associated with the ticket.
coupons array coupons Flights issued within this transaction.

coupons

Property Name Type Format Description
originationAirportIATACode string ^[a-zA-Z]{3}$ IATA airport code of the flight’s origin.
originationDateTime string date-time Date and time of origin.
destinationAirportIATACode string ^[a-zA-Z]{3}$ IATA airport code of the flight’s destination.
destinationDateTime string date-time Date and time of destination.
flightNumber string N/A Flight identifier.
couponNumber string ^(?!\s*$).+ Identifier associated with the given coupon.
operatingAirlineCode string ^[a-zA-Z]{2}$ IATA code of the airline operating the flight.
marketingCarrier string ^[a-zA-Z0-9]{3,8}$ Flight designator booking the flight.
operatingCarrier string ^[a-zA-Z0-9]{3,8}$ Flight designator operating the flight.
classOfServiceCode string ^[a-zA-Z]$ Class of service per the airline’s class of service codes. Most airlines use the same codes but some airlines have custom codes.
fareBasisCode string ^[a-zA-Z0-9]{2,8}$ Rate code the airline used to calculate the fare for this flight.
ticketDesignatorCode string ^[a-zA-Z0-9*?]{1,10}$ A valid ticket designator code to indicate what type of discount is applied, such as for a child or infant, or airline employee. This is a 1 to 10 alphanumeric code and can optionally include a single asterisk. Ticket designators are free-form text codes which help identify ticket types. Airlines determine which ticket designators they will use as no standards currently exist.
fare string ^[-]?\d*.?\d+$ Fare charged for the flight.
taxes array Taxes Schema for objects that make up an array of taxes. Used in most receipt types.
lineItems array lineItems Line Items/fees specific to a leg of the trip. Eg. Baggage fees, class of service fees, priority boarding, meals.

Definitions

Property Name Type Format Description
IATAAirportCode string ^[a-zA-Z]{3}$ 3-letter IATA code for an airport.
IATAAirlineCode string ^[a-zA-Z]{2}$ 2-letter code for an airline.
IATACityCode string ^[a-zA-Z]{3}$ 3-letter IATA city code. For example, SEA for Seattle.
IATAAgencyNumber string ^[0-9]{8}$ 8-character ID number assigned by the IATA to an agency.
flightDesignator string ^[a-zA-Z0-9]{3,8}$
classOfServiceCode string ^[a-zA-Z]$
fareBasisCode string ^[a-zA-Z0-9]{2,8}$
ticketDesignatorCode string ^[a-zA-Z0-9*?]{1,10}$

Car Rental Receipt

Schema for car rentals. This does not include ride services or taxis. * Includes all of Receipt Core Definitions

Property Name Type Format Description
itineraryLocator string ^(?!\s*$).+ Unique ID of an itinerary (also know as a trip) in Concur’s Itinerary Service. An itinerary can contain one or more bookings from various sources.
segmentLocator string ^(?!\s*$).+ Unique ID of a single travel event in Concur’s Itinerary Service. An itinerary can contain one or more bookings and each booking can contain one or more segments. The segmentLocator uniquely identifies an event like a car rental with a specific start and end date or a single air segment/sector.
startDateTime string date-time A subset of ISO 8601 date-times. The first restriction is that the dateTime requires a date, a time (at least the hour portion), and a UTC offset. The second restriction is that the dateTime does not allow a time to be formatted in UTC time (2015-11-02T14:30Z - notice the Z) without an offset; this is because it would be impossible for us to know the original offset so we could not generate a receipt with the correct local time.
endDateTime string date-time A subset of ISO 8601 date-times. The first restriction is that the dateTime requires a date, a time (at least the hour portion), and a UTC offset. The second restriction is that the dateTime does not allow a time to be formatted in UTC time (2015-11-02T14:30Z - notice the Z) without an offset; this is because it would be impossible for us to know the original offset so we could not generate a receipt with the correct local time.
pickupLocation object Location Schema representing a location, including geographical information and a postal address. Used in multiple receipt types.
dropoffLocation object Location Schema representing a location, including geographical information and a postal address. Used in multiple receipt types.
rentalDays integer N/A Total number of days for which the car was rented.
rentalAgreementNumber string N/A Agreement identifier.
confirmationNumber string N/A Booking confirmation identifier.
vehicle object vehicle
driverName string N/A Name of the driver/renter of the vehicle.
distance object distance Distance traveled.
odometerReadingOut number N/A Odometer reading at the start of the rental period. A number with up to one decimal place is expected.
odometerReadingIn number N/A Odometer reading at the end of the rental period. A number with up to one decimal place is expected.
additionalDriver boolean N/A Additional approved driver (true) or not (false).
lineItems array lineItems Break down of all car rental charges. This could include daily rate, fees, insurance, GPS rental and other add-ons.

vehicle

Property Name Type Format Description
registrationNumber string N/A Registration or license plate identifier.
description string N/A Vehicle description, including year, make and model.
classReservedCode string ^[a-zA-Z]{4}$ Four-letter Association of Car Rental Industry Systems Standard (ACRISS) car code.
classRentedCode string ^[a-zA-Z]{4}$ Actual vehicle rented ACRISS identifier.
classChargedCode string ^[a-zA-Z]{4}$ Car class code actually charged to the user.
engineSize string ^[0-9]{1,4}$ Engine displacement in cubic centimeters.

Definitions

Property Name Type Format Description
acrissCarCode string ^[a-zA-Z]{4}$ Four-letter Association of Car Rental Industry Systems Standard (ACRISS) car code.
engineSize string ^[0-9]{1,4}$ Engine displacement in cubic centimeters.

Common Definitions

Shared definitions that are utilized in multiple receipt types.

Definitions

Property Name Type Format Description
dateTime string date-time The dateTime validation validates for a subset of ISO 8601 date-times. The first restriction is that the dateTime requires a date, a time (at least the hour portion), and a UTC offset. The second restriction is that the dateTime does not allow a time to be formatted in UTC time (2015-11-02T14:30Z - notice the Z) without an offset; This is because it would be impossible for us to know the original offset so we could not generate a receipt with the correct local time.
duration string ^(-)?P(?:(-?[0-9,.])Y)?(?:(-?[0-9,.])M)?(?:(-?[0-9,.])W)?(?:(-?[0-9,.])D)?(?:T(?:(-?[0-9,.])H)?(?:(-?[0-9,.])M)?(?:(-?[0-9,.]*)S)?)?$ Duration of a time interval as defined in ISO 8601
nonEmptyString string ^(?!\s*$).+ Non-empty string. Length must be at least 1 character.
addressRegion string ^[a-zA-Z0-9]{1,3}$ 1 to 3 character country subdivision code as defined in ISO 3166-2:2013
addressCountry string country-code 2 or 3 character country code as defined in ISO 3166-1:2013
currency string ^[-]?\d*.?\d+$ String representing an amount of money. Should not include a currency code or symbol, as this information is included in the currencyCode field of the receipt.
currencyCode string currency-code 3-letter currency code as defined in ISO 4217
latitude number N/A Numeric latitude value between -90 and 90
longitude number N/A Numeric longitude value between -180 and 180
positiveInteger integer N/A Positive integer value of at least 1
positiveNumber number N/A Positive number value of at least 0
negativeCurrency string ^[-]\d*.?\d+$ String representing a negative amount of money, normally used for a discount. Should not include a currency code or symbol, as this information is included in the currencyCode field of the receipt.

distance

Property Name Type Format Description
totalDistance number N/A
unit N/A N/A Can be any of the following values: mi, km

Discount

Schema for discounts, such as coupons or discount codes, that could be part of a transaction.

Property Name Type Format Description
discountName string N/A The name of the discount.
discountCode string N/A The code for the discount.
discountRate string N/A The percentage of discount provided.
discountAmount string ^[-]\d*.?\d+$ String representing a negative amount of money, normally used for a discount. Should not include a currency code or symbol, as this information is included in the currencyCode field of the receipt.

General Receipt

General receipt type for transactions that do not fall under one of the more specific receipt types. This might include retail stores or restaurants. * Includes all of Receipt Core Definitions

Property Name Type Format Description
lineItems array lineItems Line items specified for general receipts.

Ground Transport Receipt

Schema for ground transportation receipts. This includes essentially all forms of non-aerial transportation, except those that run on railed tracks. * Includes all of Receipt Core Definitions

Property Name Type Format Description
itineraryLocator string ^(?!\s*$).+ Non-empty string. Length must be at least 1 character.
segmentLocator string ^(?!\s*$).+ Non-empty string. Length must be at least 1 character.
classOfService string ^(?!\s*$).+ Non-empty string. Length must be at least 1 character.
startDateTime string date-time A subset of ISO 8601 date-times. The first restriction is that the dateTime requires a date, a time (at least the hour portion), and a UTC offset. The second restriction is that the dateTime does not allow a time to be formatted in UTC time (2015-11-02T14:30Z - notice the Z) without an offset; this is because it would be impossible for us to know the original offset so we could not generate a receipt with the correct local time.
endDateTime string date-time A subset of ISO 8601 date-times. The first restriction is that the dateTime requires a date, a time (at least the hour portion), and a UTC offset. The second restriction is that the dateTime does not allow a time to be formatted in UTC time (2015-11-02T14:30Z - notice the Z) without an offset; this is because it would be impossible for us to know the original offset so we could not generate a receipt with the correct local time.
travelDuration string ^(-)?P(?:(-?[0-9,.])Y)?(?:(-?[0-9,.])M)?(?:(-?[0-9,.])W)?(?:(-?[0-9,.])D)?(?:T(?:(-?[0-9,.])H)?(?:(-?[0-9,.])M)?(?:(-?[0-9,.]*)S)?)?$ Duration of a time interval as defined in ISO 8601
mapUrl string Google Maps URI Pattern Link to an image of the traveled route.
pickupLocation object Location Schema representing a location, including geographical information and a postal address. Used in multiple receipt types.
dropoffLocation object Location Schema representing a location, including geographical information and a postal address. Used in multiple receipt types.
distance object distance Object representing a distance.
driverNumber string N/A Unique identifier assigned by the ride company to a driver.
lineItems array lineItems Descriptive breakdown of the fare charged. For example: base fare, distance travelled, discount and other add-ons.

Google Maps URI Pattern: ^https://(www|maps).(googleapis|google).[a-z]+/maps/

Hotel Receipt

Schema for hotel receipts. * Includes all of Receipt Core Definitions

Property Name Type Format Description
itineraryLocator string ^(?!\s*$).+ Unique ID of an itinerary (also know as a trip) in Concur’s Itinerary Service. An itinerary can contain one or more bookings from various sources.
segmentLocator string ^(?!\s*$).+ Unique ID of a single travel event in Concur’s Itinerary Service. An itinerary can contain one or more bookings and each booking can contain one or more segments. The segmentLocator uniquely identifies an event like a car rental with a specific start and end date or a single air segment/sector.
property object Location Physical property location information for the hotel property. This is often different than the merchant location information.
confirmationNumber string N/A Booking identifier.
checkInDateTime string date-time A subset of ISO 8601 date-times. The first restriction is that the dateTime requires a date, a time (at least the hour portion), and a UTC offset. The second restriction is that the dateTime does not allow a time to be formatted in UTC time (2015-11-02T14:30Z - notice the Z) without an offset; this is because it would be impossible for us to know the original offset so we could not generate a receipt with the correct local time.
checkOutDateTime string date-time A subset of ISO 8601 date-times. The first restriction is that the dateTime requires a date, a time (at least the hour portion), and a UTC offset. The second restriction is that the dateTime does not allow a time to be formatted in UTC time (2015-11-02T14:30Z - notice the Z) without an offset; this is because it would be impossible for us to know the original offset so we could not generate a receipt with the correct local time.
guests array guests Guest information.
numberInParty integer N/A Number of individuals for the stay.
room object room
nightsStayed integer N/A Positive integer value of at least 1
lineItems array lineItems

guests

Property Name Type Format Description
guestNameRecord string N/A The loyalty or membership number of the hotel guest.
firstName string ^(?!\s*$).+ Non-empty string. Length must be at least 1 character.
lastName string ^(?!\s*$).+ Non-empty string. Length must be at least 1 character.
address object Address Address of the guest. It is highly recommended that the business address of the guest is provided if the hotel is provided with one. Doing so will help VAT reclamation partners who work with companies, to have compliant receipts accepted by the tax authority when filing tax reclaims.

property

Property Name Type Format Description
name string N/A The name for the location.
number string N/A The identifier the company assigned to this location.
latitude number N/A Numeric latitude value between -90 and 90
longitude number N/A Numeric longitude value between -180 and 180
internetAddress string N/A
emailAddress string N/A
telephoneNumber string N/A
faxNumber string N/A
address object Address Common address object used by all receipt types except for the JPT IC Card receipt, which uses Address-Original.

room

Property Name Type Format Description
roomNumber string N/A Room number where the guest stayed.
roomType string N/A Type of room where the guest stayed. For example, Standard, Deluxe, etc.
ratePlanType string N/A Name of the rate plan according to which the guest was charged.
averageDailyRoomRate string ^[-]?\d*.?\d+$ Average of the daily room rates for the duration of the guests stay. Room rates usually differ from day to day.

segments

Property Name Type Format Description
sequenceNumber integer N/A Unique transaction identifier for every trip taken using the IC card.
dateTime string date-time A subset of ISO 8601 date-times. The first restriction is that the dateTime requires a date, a time (at least the hour portion), and a UTC offset. The second restriction is that the dateTime does not allow a time to be formatted in UTC time (2015-11-02T14:30Z - notice the Z) without an offset; this is because it would be impossible for us to know the original offset so we could not generate a receipt with the correct local time.
fromStationCode string N/A Departure station code of the route. This code is specified to the IC Card vendor. Concur Expense has a transcoding table to Expense location codes.
fromStationName string N/A Departure station label of the route.
toStationCode string N/A Arrival station code of the route. This code is specified to the IC Card vendor. Concur Expense has a transcoding table to Expense location codes.
toStationName string N/A Arrival station label of the route.
fromIsCommuterPass boolean N/A Whether or not the departure route is included in the commuter pass subscription of the employee.
toIsCommuterPass boolean N/A Whether or not the arrival route is included in the commuter pass subscription of the employee.
distance number N/A Positive number value of at least value as 0

icCardSegment

Property Name Type Format Description
sequenceNumber integer N/A Unique transaction identifier for every trip taken using the IC card.
dateTime string date-time Transaction date and time.
fromStationCode string N/A Departure station code of the route. This code is specified to the IC Card vendor. Concur Expense has a transcoding table to Expense location codes.
fromStationName string N/A Departure station label of the route.
toStationCode string N/A Arrival station code of the route. This code is specified to the IC Card vendor. Concur Expense has a transcoding table to Expense location codes.
toStationName string N/A Arrival station label of the route.
fromIsCommuterPass boolean N/A Whether or not the departure route is included in the commuter pass subscription of the employee.
toIsCommuterPass boolean N/A Whether or not the arrival route is included in the commuter pass subscription of the employee.
distance number N/A Positive number value of at least value as 0

Line Item

Generic line item. These objects are included in arrays in most receipt types.

Property Name Type Format Description
sequenceNumber integer N/A The order in which the item appears in the sequence of line items when the receipt is rendered by Concur.
dateTime string date-time A subset of ISO 8601 date-times. The first restriction is that the dateTime requires a date, a time (at least the hour portion), and a UTC offset. The second restriction is that the dateTime does not allow a time to be formatted in UTC time (2015-11-02T14:30Z - notice the Z) without an offset; this is because it would be impossible for us to know the original offset so we could not generate a receipt with the correct local time.
reference string N/A The item SKU, identifier or some other attribute the merchant uses to reference the item.
description string ^(?!\s*$).+ Non-empty string. Length must be at least 1 character.
additionalDescription string N/A
semanticsCode string ^(?!\s*$).+ The Concur semantics code for the line item.
unitCost string ^[-]?\d*.?\d+$ Amount per unit.
quantity integer N/A
total string ^[-]?\d*.?\d+$ String representing an amount of money. Should not include a currency code or symbol, as this information is included in the currencyCode field of the receipt.
subtotal string ^[-]?\d*.?\d+$ String representing an amount of money. Should not include a currency code or symbol, as this information is included in the currencyCode field of the receipt.
taxesTotal string ^[-]?\d*.?\d+$ String representing an amount of money. Should not include a currency code or symbol, as this information is included in the currencyCode field of the receipt.
taxes array Taxes Schema for objects that make up an array of taxes. Used in most receipt types.
vatApplicable boolean N/A If the line item was subject to a value added tax then true, if not then false.
amountIncludesVat boolean N/A
discounts array discounts The discounts offered for this line item.

Location

Schema representing a location, including geographical information and a postal address. Used in multiple receipt types.

Property Name Type Format Description
name string N/A The name for the location.
number string N/A The identifier the company assigned to this location.
latitude number N/A Numeric latitude value between -90 and 90
longitude number N/A Numeric longitude value between -180 and 180
internetAddress string N/A
emailAddress string N/A
telephoneNumber string N/A
faxNumber string N/A
address object Address Common address object used by all receipt types except for the JPT IC Card receipt, which uses Address-Original.

Merchant

Schema for an object representing a merchant. The broker and seller properties in all receipts use this schema.

Property Name Type Format Description
name string ^(?!\s*$).+ Non-empty string. Length must be at least 1 character.
description string N/A Description of the service provided by the merchant.
taxId string N/A The tax identification number assigned to the merchant by the national tax authority. If the partner is providing a tax invoice, then providing a tax identification number is recommended.
location object Location Schema representing a location, including geographical information and a postal address. Used in multiple receipt types.

Payments

The payments array allows for one or more payment methods used in the transaction to be defined. All payment methods defined within the array result in the value for total in the base object of the receipt. The JSON keyword ‘anyOf’ indicates at least one of the following is required and multiple can be present: cash, creditCard, companyPaid, digitalWallet and / or unusedTicket.

cash

Property Name Type Format Description
amount string ^[-]?\d*.?\d+$ String representing an amount of money. Should not include a currency code or symbol, as this information is included in the currencyCode field of the receipt.

creditCard

Property Name Type Format Description
amount string ^[-]?\d*.?\d+$ String representing an amount of money. Should not include a currency code or symbol, as this information is included in the currencyCode field of the receipt.
cardDetail object cardDetail Credit card information.

cardDetail

Property Name Type Format Description
cardType N/A N/A Can be any of the following values: American Express, Diners Club, Discover, MasterCard, Visa, Carte Blanche, Enroute, Universal Air Travel, JCB, EuroCard
creditCardId string ^[0-9]{4}$ Last four digits of the credit card number to meet FACTA and PCI requirements
authorizationCode string N/A Authorization code for transaction.

companyPaid

Property Name Type Format Description
source N/A N/A Can be any of the following values: GhostCard, LodgeCard, DirectPay, Invoice
amount string ^[-]?\d*.?\d+$ String representing an amount of money. Should not include a currency code or symbol, as this information is included in the currencyCode field of the receipt.
cardDetail object cardDetail Credit card information.

cardDetail

Property Name Type Format Description
cardType N/A N/A Can be any of the following values: American Express, Diners Club, Discover, MasterCard, Visa, Carte Blanche, Enroute, Universal Air Travel, JCB, EuroCard
creditCardId string ^[0-9]{4}$ Last four digits of the credit card number to meet FACTA and PCI requirements
authorizationCode string N/A Authorization code for transaction.

digitalWallet

Property Name Type Format Description
source N/A N/A Can be any of the following values: ApplePay, AndroidPay, SamsungPay, PayPal, OlaMoney
amount string ^[-]?\d*.?\d+$ String representing an amount of money. Should not include a currency code or symbol, as this information is included in the currencyCode field of the receipt.

unusedTicket

Property Name Type Format Description
ticketNumber string ^(?!\s*$).+ Non-empty string. Length must be at least 1 character.
amount string ^[-]?\d*.?\d+$ String representing an amount of money. Should not include a currency code or symbol, as this information is included in the currencyCode field of the receipt.

cardDetail

Property Name Type Format Description
cardType N/A N/A Can be any of the following values: American Express, Diners Club, Discover, MasterCard, Visa, Carte Blanche, Enroute, Universal Air Travel, JCB, EuroCard
creditCardId string ^[0-9]{4}$ Last four digits of the credit card number to meet FACTA and PCI requirements
authorizationCode string N/A Authorization code for transaction.

Rail Receipt

Schema for rail or train receipts. * Includes all of Receipt Core Definitions

Property Name Type Format Description
itineraryLocator string ^(?!\s*$).+ Unique ID of an itinerary (also know as a trip) in Concur’s Itinerary Service. An itinerary can contain one or more bookings from various sources.
lineItems array lineItems Break down of all charges which could include insurance purchased for all train tickets, paid wi-fi etc.
railTickets array railTickets

railTickets

Property Name Type Format Description
ticketNumber string N/A
recordLocator string N/A Confirmation identifier for the ticket. This code is usually unique for a short period of time and could be reused by the rail company in the future.
issueDateTime string date-time Date and time the ticket was issued.
passengerName string N/A Name of the person associated withthe ticket.
fare string ^[-]?\d*.?\d+$ Fare charged for a train ticket. This will be the total of all segments in this train ticket.
segments array segments Segments for this train ticket.

segments

Property Name Type Format Description
departureStation string N/A Name of the station from which the train is departing.
departureDateTime string date-time A subset of ISO 8601 date-times. The first restriction is that the dateTime requires a date, a time (at least the hour portion), and a UTC offset. The second restriction is that the dateTime does not allow a time to be formatted in UTC time (2015-11-02T14:30Z - notice the Z) without an offset; this is because it would be impossible for us to know the original offset so we could not generate a receipt with the correct local time.
arrivalStation string N/A Name of the station where the train is arriving.
arrivalDateTime string date-time A subset of ISO 8601 date-times. The first restriction is that the dateTime requires a date, a time (at least the hour portion), and a UTC offset. The second restriction is that the dateTime does not allow a time to be formatted in UTC time (2015-11-02T14:30Z - notice the Z) without an offset; this is because it would be impossible for us to know the original offset so we could not generate a receipt with the correct local time.
trainNumber string N/A Train identifier
trainType string N/A Type of train. For example TGV or TER in France.
classOfServiceCode string ^(?!\s*$).+ The class of travel.
fare string ^[-]?\d*.?\d+$ Fare charged for this segment of the train ride.
taxes array Taxes Taxes paid for this segment.
lineItems array lineItems Line items specific to this segment. This could include meals, seat reservations, insurance etc.

Receipt Core Definitions

Core values for all receipt types. All major receipt schemas include these core objects.

Property Name Type Format Description
dateTime string date-time Date and time of the transaction.
total string ^[-]?\d*.?\d+$ The total amount of the transaction including all lineitems and taxes.
subtotal string ^[-]?\d*.?\d+$ The amount in the transaction excluding taxes.
taxesTotal string ^[-]?\d*.?\d+$ The amount of tax paid in the transaction.
discountsTotal string ^[-]\d*.?\d+$ String representing a negative amount of money, normally used for a discount. Should not include a currency code or symbol, as this information is included in the currencyCode field of the receipt.
currencyCode string currency-code Currency paid to the merchant.
broker object Merchant The entity that facilitates the transaction between the seller and end user.
seller object Merchant The entity providing service to the end user.
payments array Payments
discounts array discounts The discounts offered on this transaction.
taxes array Taxes Taxes paid as part of transaction.
reference string N/A The unique receipt provider or merchant identifier for this receipt or invoice. This value can also be referred to as transaction number, check number, order ID or similar.
collectionReference string N/A Use this key to group related receipts into a collection for credits, tips or other adjustments to the original transaction and looking at groups of receipts for analysis purposes. The reference and collectionReference keys typically have separate and unique values but could be the same for the first receipt in a collection.
taxInvoice boolean N/A A tax invoice (true) or otherwise (false).

broker

Property Name Type Format Description
name string ^(?!\s*$).+ Non-empty string. Length must be at least 1 character.
description string N/A Description of the service provided by the merchant.
taxId string N/A The tax identification number assigned to the merchant by the national tax authority. If the partner is providing a tax invoice, then providing a tax identification number is recommended.
location object Location Schema representing a location, including geographical information and a postal address. Used in multiple receipt types.

seller

Property Name Type Format Description
name string ^(?!\s*$).+ Non-empty string. Length must be at least 1 character.
description string N/A Description of the service provided by the merchant.
taxId string N/A The tax identification number assigned to the merchant by the national tax authority. If the partner is providing a tax invoice, then providing a tax identification number is recommended.
location object Location Schema representing a location, including geographical information and a postal address. Used in multiple receipt types.

Taxes

Schema for objects that make up an array of taxes. Used in most receipt types.

Property Name Type Format Description
authority object authority The country or subdivision that charged the tax as per ISO 3166-2:2013.
name string N/A
rate number N/A
rateType string N/A The rate type for the tax charged. For value added tax this could be Zero, Standard, Reduced, etc.
amount string ^[-]?\d*.?\d+$ String representing an amount of money. Should not include a currency code or symbol, as this information is included in the currencyCode field of the receipt.

authority

Property Name Type Format Description
addressCountry string country-code 2 or 3 character country code as defined in ISO 3166-1:2013
addressRegion string ^[a-zA-Z0-9]{1,3}$ 1 to 3 character country subdivision code as defined in ISO 3166-2:2013

Sample Receipts

Below we have sample receipt data and the corresponding receipt images for the following receipt types:

Air (Multiple Tickets)

Receipt Data

{
    "taxInvoice": true,
    "reference": "ABCD1234",
    "dateTime": "2099-11-10T16:04:49-0700",
    "total": "1400.40",
    "taxesTotal": "123.38",
    "subtotal": "1277.02",
    "currencyCode": "USD",
    "broker": {
        "name": "ACME Corporation",
        "description": "",
        "taxId": "123-21213",
        "location": {
            "name": "Headquarters",
            "number": "",
            "latitude": 41.8819,
            "longitude": -87.6278,
            "internetAddress": "http://www.acmecorporation.com",
            "emailAddress": "info@acmecorporation.com",
            "telephoneNumber": "1-877-555-5555",
            "faxNumber": "",
            "address": {
                "streetAddress": "333 108th Ave NE",
                "addressLocality": "Bellevue",
                "addressRegion": "WA",
                "addressCountry": "US",
                "postalCode": "98004"
            }
        }
    },
    "seller": {
        "name": "ACME Airlines",
        "description": "",
        "taxId": "867-53090",
        "location": {
            "name": "Headquarters",
            "number": "",
            "latitude": 37.2714,
            "longitude": -85.3262,
            "internetAddress": "http://www.acmeairlines.com",
            "emailAddress": "contact@acmeairlines.com",
            "telephoneNumber": "1-888-555-5555",
            "faxNumber": "",
            "address": {
                "streetAddress": "1 Ground Transport Way",
                "addressLocality": "Seattle",
                "addressRegion": "WA",
                "addressCountry": "US",
                "postalCode": "90001"
            }
        }
    },
    "taxes": [
        {
            "authority": {
                "addressCountry": "US",
                "addressRegion": "WA"
            },
            "name": "Transportation Tax",
            "rate": 7.50,
            "amount": "91.38"
        },
        {
            "authority": {
                "addressCountry": "US"
            },
            "name": "United States - Flight Segment Tax",
            "rate": 10.0,
            "amount": "32.00"
        }
    ],
    "payments": [
        {
            "amount": "1400.40",
            "cardDetail": {
                "cardType": "Visa",
                "creditCardId": "7423",
                "authorizationCode": "AB123654789"
            }
        }
    ],
    "itineraryLocator": "1122337694093",
    "tickets": [
        {
            "number": "0062698215636",
            "recordLocator": "CU9GEF",
            "issueDateTime": "2015-11-29T19:15:55-0700",
            "pseudoCityCode": "SEA",
            "IATAAgencyNumber": "87654321",
            "agencyName": "ACME Airlines",
            "passengerName": "Jimmy Dean",
            "fare": "609.31",
            "coupons": [
                {
                    "originationAirportIATACode": "SEA",
                    "originationDateTime": "2015-12-25T09:00:00-0700",
                    "destinationAirportIATACode": "MSP",
                    "destinationDateTime": "2015-12-25T14:14:00-0500",
                    "flightNumber": "DL 1768",
                    "couponNumber": "D167693",
                    "operatingAirlineCode": "DL",
                    "marketingCarrier": "DL1768",
                    "operatingCarrier": "DL1768",
                    "classOfServiceCode": "T",
                    "fareBasisCode": "YHRT15",
                    "ticketDesignatorCode": "FSG*SFR",
                    "fare": "152.33",
                    "taxes": [
                        {
                            "authority": {
                                "addressCountry": "US"
                            },
                            "name": "Transportation Tax",
                            "rate": 7.50,
                            "amount": "11.42"
                        }
                    ],
                    "lineItems": [
                        {
                            "sequenceNumber": 1,
                            "description": "United States - September 11th Security Fee",
                            "additionalDescription": "Passenger Civil Aviation Security Service Fee",
                            "semanticsCode": "OTHER",
                            "dateTime": "2015-11-29T19:15:55-0700",
                            "total": "2.80"
                        },
                        {
                            "sequenceNumber": 2,
                            "description": "United States - Passenger Facility Charge",
                            "additionalDescription": "",
                            "semanticsCode": "SEGFEE_AS_FEE",
                            "dateTime": "2015-11-29T19:15:55-0700",
                            "total": "4.50"
                        },
                        {
                            "sequenceNumber": 3,
                            "description": "United States - Flight Segment Tax",
                            "additionalDescription": "",
                            "semanticsCode": "SEGFEE_AS_TAX",
                            "dateTime": "2015-11-29T19:15:55-0700",
                            "total": "4.00"
                        }
                    ]
                },
                {
                    "originationAirportIATACode": "MSP",
                    "originationDateTime": "2015-12-25T15:25:00-0500",
                    "destinationAirportIATACode": "GFK",
                    "destinationDateTime": "2015-12-25T16:50:00-0500",
                    "flightNumber": "OO 4656",
                    "couponNumber": "D187322",
                    "operatingAirlineCode": "DL",
                    "marketingCarrier": "DL1768Z",
                    "operatingCarrier": "OO4656B",
                    "classOfServiceCode": "T",
                    "fareBasisCode": "YAD1234",
                    "ticketDesignatorCode": "FSG*SFR",
                    "fare": "121.86",
                    "taxes": [
                        {
                            "authority": {
                                "addressCountry": "US"
                            },
                            "name": "Transportation Tax",
                            "rate": 7.50,
                            "amount": "9.14"
                        }
                    ],
                    "lineItems": [
                        {
                            "sequenceNumber": 1,
                            "description": "United States - September 11th Security Fee",
                            "additionalDescription": "Passenger Civil Aviation Security Service Fee",
                            "semanticsCode": "OTHER",
                            "dateTime": "2015-11-29T19:15:55-0700",
                            "total": "2.24"
                        },
                        {
                            "sequenceNumber": 2,
                            "description": "United States - Passenger Facility Charge",
                            "additionalDescription": "",
                            "semanticsCode": "SEGFEE_AS_FEE",
                            "dateTime": "2015-11-29T19:15:55-0700",
                            "total": "3.60"
                        },
                        {
                            "sequenceNumber": 3,
                            "description": "United States - Flight Segment Tax",
                            "additionalDescription": "",
                            "semanticsCode": "SEGFEE_AS_TAX",
                            "dateTime": "2015-11-29T19:15:55-0700",
                            "total": "4.00"
                        }
                    ]
                },
                {
                    "originationAirportIATACode": "GFK",
                    "originationDateTime": "2015-12-30T17:19:00-0500",
                    "destinationAirportIATACode": "MSP",
                    "destinationDateTime": "2015-12-30T18:34:00-0500",
                    "flightNumber": "OO 4656",
                    "couponNumber": "D187322",
                    "operatingAirlineCode": "DL",
                    "marketingCarrier": "DL1768Z",
                    "operatingCarrier": "OO4656B",
                    "classOfServiceCode": "T",
                    "fareBasisCode": "YAD1234",
                    "ticketDesignatorCode": "FSG*SFR",
                    "fare": "140.14",
                    "taxes": [
                        {
                            "authority": {
                                "addressCountry": "US"
                            },
                            "name": "Transportation Tax",
                            "rate": 7.50,
                            "amount": "10.51"
                        }
                    ],
                    "lineItems": [
                        {
                            "sequenceNumber": 1,
                            "description": "United States - September 11th Security Fee",
                            "additionalDescription": "Passenger Civil Aviation Security Service Fee",
                            "semanticsCode": "OTHER",
                            "dateTime": "2015-11-29T19:15:55-0700",
                            "total": "2.58"
                        },
                        {
                            "sequenceNumber": 2,
                            "description": "United States - Passenger Facility Charge",
                            "additionalDescription": "",
                            "semanticsCode": "SEGFEE_AS_FEE",
                            "dateTime": "2015-11-29T19:15:55-0700",
                            "total": "4.14"
                        },
                        {
                            "sequenceNumber": 3,
                            "description": "United States - Flight Segment Tax",
                            "additionalDescription": "",
                            "semanticsCode": "SEGFEE_AS_TAX",
                            "dateTime": "2015-11-29T19:15:55-0700",
                            "total": "4.00"
                        }
                    ]
                },
                {
                    "originationAirportIATACode": "MSP",
                    "originationDateTime": "2015-12-30T19:25:00-0500",
                    "destinationAirportIATACode": "SEA",
                    "destinationDateTime": "2015-12-30T21:15:00-0700",
                    "flightNumber": "DL 2536",
                    "couponNumber": "D187322",
                    "operatingAirlineCode": "DL",
                    "marketingCarrier": "DL2536Z",
                    "operatingCarrier": "DL2536B",
                    "classOfServiceCode": "T",
                    "fareBasisCode": "YAD1234",
                    "ticketDesignatorCode": "FSG*SFR",
                    "fare": "194.98",
                    "taxes": [
                        {
                            "authority": {
                                "addressCountry": "US"
                            },
                            "name": "Transportation Tax",
                            "rate": 7.50,
                            "amount": "14.62"
                        }
                    ],
                    "lineItems": [
                        {
                            "sequenceNumber": 1,
                            "description": "United States - September 11th Security Fee",
                            "additionalDescription": "Passenger Civil Aviation Security Service Fee",
                            "semanticsCode": "OTHER",
                            "dateTime": "2015-11-29T19:15:55-0700",
                            "total": "3.58"
                        },
                        {
                            "sequenceNumber": 2,
                            "description": "United States - Passenger Facility Charge",
                            "additionalDescription": "",
                            "semanticsCode": "SEGFEE_AS_FEE",
                            "dateTime": "2015-11-29T19:15:55-0700",
                            "total": "5.76"
                        },
                        {
                            "sequenceNumber": 3,
                            "description": "United States - Flight Segment Tax",
                            "additionalDescription": "",
                            "semanticsCode": "SEGFEE_AS_TAX",
                            "dateTime": "2015-11-29T19:15:55-0700",
                            "total": "4.00"
                        }
                    ]
                }
            ]
        },
        {
            "number": "0062698215637",
            "recordLocator": "CU9GEF",
            "issueDateTime": "2015-11-29T19:15:55-0700",
            "pseudoCityCode": "SEA",
            "IATAAgencyNumber": "87654321",
            "agencyName": "ACME Airlines",
            "passengerName": "John Smith",
            "fare": "609.31",
            "coupons": [
                {
                    "originationAirportIATACode": "SEA",
                    "originationDateTime": "2015-12-25T09:00:00-0700",
                    "destinationAirportIATACode": "MSP",
                    "destinationDateTime": "2015-12-25T14:14:00-0500",
                    "flightNumber": "DL 1768",
                    "couponNumber": "D167693",
                    "operatingAirlineCode": "DL",
                    "marketingCarrier": "DL1768",
                    "operatingCarrier": "DL1768",
                    "classOfServiceCode": "T",
                    "fareBasisCode": "YHRT15",
                    "ticketDesignatorCode": "FSG*SFR",
                    "fare": "152.33",
                    "taxes": [
                        {
                            "authority": {
                                "addressCountry": "US"
                            },
                            "name": "Transportation Tax",
                            "rate": 7.50,
                            "amount": "11.42"
                        }
                    ],
                    "lineItems": [
                        {
                            "sequenceNumber": 1,
                            "description": "United States - September 11th Security Fee",
                            "additionalDescription": "Passenger Civil Aviation Security Service Fee",
                            "semanticsCode": "OTHER",
                            "dateTime": "2015-11-29T19:15:55-0700",
                            "total": "2.80"
                        },
                        {
                            "sequenceNumber": 2,
                            "description": "United States - Passenger Facility Charge",
                            "additionalDescription": "",
                            "semanticsCode": "SEGFEE_AS_FEE",
                            "dateTime": "2015-11-29T19:15:55-0700",
                            "total": "4.50"
                        },
                        {
                            "sequenceNumber": 3,
                            "description": "United States - Flight Segment Tax",
                            "additionalDescription": "",
                            "semanticsCode": "SEGFEE_AS_TAX",
                            "dateTime": "2015-11-29T19:15:55-0700",
                            "total": "4.00"
                        }
                    ]
                },
                {
                    "originationAirportIATACode": "MSP",
                    "originationDateTime": "2015-12-25T15:25:00-0500",
                    "destinationAirportIATACode": "GFK",
                    "destinationDateTime": "2015-12-25T16:50:00-0500",
                    "flightNumber": "OO 4656",
                    "couponNumber": "D187322",
                    "operatingAirlineCode": "DL",
                    "marketingCarrier": "DL1768Z",
                    "operatingCarrier": "OO4656B",
                    "classOfServiceCode": "T",
                    "fareBasisCode": "YAD1234",
                    "ticketDesignatorCode": "FSG*SFR",
                    "fare": "121.86",
                    "taxes": [
                        {
                            "authority": {
                                "addressCountry": "US"
                            },
                            "name": "Transportation Tax",
                            "rate": 7.50,
                            "amount": "9.14"
                        }
                    ],
                    "lineItems": [
                        {
                            "sequenceNumber": 1,
                            "description": "United States - September 11th Security Fee",
                            "additionalDescription": "Passenger Civil Aviation Security Service Fee",
                            "semanticsCode": "OTHER",
                            "dateTime": "2015-11-29T19:15:55-0700",
                            "total": "2.24"
                        },
                        {
                            "sequenceNumber": 2,
                            "description": "United States - Passenger Facility Charge",
                            "additionalDescription": "",
                            "semanticsCode": "SEGFEE_AS_FEE",
                            "dateTime": "2015-11-29T19:15:55-0700",
                            "total": "3.60"
                        },
                        {
                            "sequenceNumber": 3,
                            "description": "United States - Flight Segment Tax",
                            "additionalDescription": "",
                            "semanticsCode": "SEGFEE_AS_TAX",
                            "dateTime": "2015-11-29T19:15:55-0700",
                            "total": "4.00"
                        }
                    ]
                },
                {
                    "originationAirportIATACode": "GFK",
                    "originationDateTime": "2015-12-30T17:19:00-0500",
                    "destinationAirportIATACode": "MSP",
                    "destinationDateTime": "2015-12-30T18:34:00-0500",
                    "flightNumber": "OO 4656",
                    "couponNumber": "D187322",
                    "operatingAirlineCode": "DL",
                    "marketingCarrier": "DL1768Z",
                    "operatingCarrier": "OO4656B",
                    "classOfServiceCode": "T",
                    "fareBasisCode": "YAD1234",
                    "ticketDesignatorCode": "FSG*SFR",
                    "fare": "140.14",
                    "taxes": [
                        {
                            "authority": {
                                "addressCountry": "US"
                            },
                            "name": "Transportation Tax",
                            "rate": 7.50,
                            "amount": "10.51"
                        }
                    ],
                    "lineItems": [
                        {
                            "sequenceNumber": 1,
                            "description": "United States - September 11th Security Fee",
                            "additionalDescription": "Passenger Civil Aviation Security Service Fee",
                            "semanticsCode": "OTHER",
                            "dateTime": "2015-11-29T19:15:55-0700",
                            "total": "2.58"
                        },
                        {
                            "sequenceNumber": 2,
                            "description": "United States - Passenger Facility Charge",
                            "additionalDescription": "",
                            "semanticsCode": "SEGFEE_AS_FEE",
                            "dateTime": "2015-11-29T19:15:55-0700",
                            "total": "4.14"
                        },
                        {
                            "sequenceNumber": 3,
                            "description": "United States - Flight Segment Tax",
                            "additionalDescription": "",
                            "semanticsCode": "SEGFEE_AS_TAX",
                            "dateTime": "2015-11-29T19:15:55-0700",
                            "total": "4.00"
                        }
                    ]
                },
                {
                    "originationAirportIATACode": "MSP",
                    "originationDateTime": "2015-12-30T19:25:00-0500",
                    "destinationAirportIATACode": "SEA",
                    "destinationDateTime": "2015-12-30T21:15:00-0700",
                    "flightNumber": "DL 2536",
                    "couponNumber": "D187322",
                    "operatingAirlineCode": "DL",
                    "marketingCarrier": "DL2536Z",
                    "operatingCarrier": "DL2536B",
                    "classOfServiceCode": "T",
                    "fareBasisCode": "YAD1234",
                    "ticketDesignatorCode": "FSG*SFR",
                    "fare": "194.98",
                    "taxes": [
                        {
                            "authority": {
                                "addressCountry": "US"
                            },
                            "name": "Transportation Tax",
                            "rate": 7.50,
                            "amount": "14.62"
                        }
                    ],
                    "lineItems": [
                        {
                            "sequenceNumber": 1,
                            "description": "United States - September 11th Security Fee",
                            "additionalDescription": "Passenger Civil Aviation Security Service Fee",
                            "semanticsCode": "OTHER",
                            "dateTime": "2015-11-29T19:15:55-0700",
                            "total": "3.58"
                        },
                        {
                            "sequenceNumber": 2,
                            "description": "United States - Passenger Facility Charge",
                            "additionalDescription": "",
                            "semanticsCode": "SEGFEE_AS_FEE",
                            "dateTime": "2015-11-29T19:15:55-0700",
                            "total": "5.76"
                        },
                        {
                            "sequenceNumber": 3,
                            "description": "United States - Flight Segment Tax",
                            "additionalDescription": "",
                            "semanticsCode": "SEGFEE_AS_TAX",
                            "dateTime": "2015-11-29T19:15:55-0700",
                            "total": "4.00"
                        }
                    ]
                }
            ]
        }
    ],
    "lineItems": [
        {
            "sequenceNumber": 1,
            "description": "United States - September 11th Security Fee",
            "additionalDescription": "Passenger Civil Aviation Security Service Fee",
            "semanticsCode": "OTHER",
            "dateTime": "2015-11-29T19:15:55-0700",
            "total": "22.40"
        },
        {
            "sequenceNumber": 2,
            "description": "United States - Passenger Facility Charge",
            "additionalDescription": "",
            "semanticsCode": "SEGFEE_AS_FEE",
            "dateTime": "2015-11-29T19:15:55-0700",
            "total": "36.00"
        }
    ]
}

Generated Receipt Image

A Receipt Image

Car Rental

Receipt Data

{
    "taxInvoice": true,
    "reference": "ABCD1234",
    "dateTime": "2016-09-29T15:05:00-0800",
    "total": "112.71",
    "taxesTotal": "8.27",
    "subtotal": "104.44",
    "currencyCode": "USD",
    "seller": {
        "name": "ACME Corporation",
        "description": "",
        "taxId": "123-21213",
        "location": {
            "name": "SNA Airport",
            "number": "SNA34393",
            "latitude": 47.616667,
            "longitude": -122.333333,
            "internetAddress": "https://www.acmecorporation.com",
            "emailAddress": "sna_airport@acmecorporation.com",
            "telephoneNumber": "123-456-7890",
            "faxNumber": "",
            "address": {
                "streetAddress": "1 Airport Way",
                "addressLocality": "Seattle",
                "addressRegion": "WA",
                "addressCountry": "US",
                "postalCode": "90001"
            }
        }
    },
    "taxes": [
        {
            "authority": {
                "addressCountry": "US",
                "addressRegion": "WA"
            },
            "name": "Local Sales Tax",
            "rate": 8.80,
            "amount": "8.27"
        }
    ],
    "payments": [
        {
            "amount": "112.71",
            "cardDetail": {
                "cardType": "American Express",
                "creditCardId": "1009",
                "authorizationCode": "AB987654321"
            }
        }
    ],
    "startDateTime": "2014-11-05T15:05:00-0800",
    "endDateTime": "2014-11-07T15:05:00-0800",
    "rentalDays": 2,
    "discounts": [{
        "discountCode": "NO-IRS",
        "discountName": "The Family of the King shall pay less",
        "discountRate": "Per Mile"
    }
    ],
    "rentalAgreementNumber": "570344843",
    "confirmationNumber": "",
    "vehicle": {
        "registrationNumber": "",
        "description": "KIA SORENTO 2WD",
        "classReservedCode": "IDAR",
        "classRentedCode": "IDAR",
        "classChargedCode": "IDAR",
        "engineSize": "2000",
        "fuelType": "Petrol"
    },
    "distance": {
        "totalDistance": 345.6,
        "unit": "mi"
    },
    "odometerReadingOut": 31548,
    "odometerReadingIn": 31893,
    "additionalDriver": false,
    "pickupLocation": {
        "name": "House of Stark",
        "address": {
            "streetAddress": "1 Wolf Road",
            "addressLocality": "Winterfell",
            "addressCountry": "GB"
        }
    },
    "dropoffLocation": {
        "name": "The Iron Throne",
        "address": {
            "streetAddress": "42 Shadowblack Lane",
            "addressLocality": "King's Landing",
            "addressCountry": "GB"
        }
    },
    "lineItems": [
        {
            "sequenceNumber": 1,
            "reference": "",
            "description": "2 DY@ 47.00",
            "additionalDescription": "",
            "semanticsCode": "DAYS",
            "quantity": 1,
            "total": "94.00",
            "taxes": [
                {
                    "authority": {
                        "addressCountry": "US",
                        "addressRegion": "CA"
                    },
                    "name": "Local Sales Tax",
                    "rate": 8.80,
                    "amount": "8.27"
                }
            ]
        },
        {
            "sequenceNumber": 2,
            "reference": "",
            "description": "11.11% FEE",
            "additionalDescription": "",
            "semanticsCode": "AIRPORTFEE",
            "quantity": 1,
            "total": "10.44"
        }
    ]
}

Generated Receipt Image

Car Rental Receipt Image

Sample Receipts - Hotel

Receipt Data

{
    "taxInvoice": true,
    "reference": "6343430",
    "dateTime": "2016-09-29T15:05:00-0800",
    "total": "749.95",
    "subtotal": "652.67",
    "taxesTotal": "97.28",
    "currencyCode": "CAD",
    "seller": {
        "name": "ACME Corporation",
        "description": "",
        "taxId": "123-21213",
        "location": {
            "name": "ACME Hotels",
            "number": "ACME34393",
            "latitude": 47.616667,
            "longitude": -122.333333,
            "internetAddress": "https://www.acmecorporation.com",
            "emailAddress": "sna_hotel@acmecorporation.com",
            "telephoneNumber": "123-456-7890",
            "faxNumber": "",
            "address": {
                "streetAddress": "1 Hotel Way",
                "addressLocality": "Seattle",
                "addressRegion": "WA",
                "addressCountry": "US",
                "postalCode": "90001"
            }
        }
    },
    "taxes": [
        {
            "authority": {
                "addressCountry": "CA"
            },
            "name": "Hotel Room Tax",
            "rate": 11.00,
            "amount": "66.88"
        },
        {
            "authority": {
                "addressCountry": "CA"
            },
            "name": "GST",
            "rateType": "Standard",
            "rate": 5.00,
            "amount": "30.4"
        }
    ],
    "payments": [
        {
            "amount": "749.95",
            "cardDetail": {
                "cardType": "American Express",
                "creditCardId": "1002",
                "authorizationCode": "548283"
            }
        }
    ],
    "property": {
        "name": "Grand Hotel",
        "number": "",
        "latitude": 49.280011,
        "longitude": -123.117024,
        "internetAddress": "",
        "emailAddress": "",
        "telephoneNumber": "123-456-1999",
        "faxNumber": "123-456-2502",
        "address": {
            "streetAddress": "433 Hotel Street",
            "addressLocality": "Vancouver",
            "addressRegion": "BC",
            "addressCountry": "CA",
            "postalCode": "v6b 6l9"
        }
    },
    "checkInDateTime": "2016-08-25T21:11:00-0700",
    "checkOutDateTime": "2016-08-27T11:09:00-0700",
    "guests": [
        {
            "guestNameRecord": "ACME-Axxxxxxx1899",
            "firstName": "Jon",
            "lastName": "Snow",
            "address": {
                "streetAddress": "111 Black Castle",
                "addressLocality": "Toronto",
                "addressRegion": "ON",
                "addressCountry": "CA",
                "postalCode": "M2P 2B8"
            }
        }
    ],
    "numberInParty": 1,
    "room": {
        "roomNumber": "1601",
        "averageDailyRoomRate": "304.00"
    },
    "nightsStayed": 2,
    "lineItems": [
        {
            "sequenceNumber": 1,
            "dateTime": "2016-04-25T18:00:00-0700",
            "reference": "RT1601",
            "description": "Room Chrg Retail",
            "semanticsCode": "ROOMRATE",
            "quantity": 1,
            "total": "304.00",
            "taxes": [
                {
                    "authority": {
                        "addressCountry": "CA"
                    },
                    "name": "Hotel Room Tax",
                    "rate": 11.00,
                    "amount": "33.44"
                },
                {
                    "authority": {
                        "addressCountry": "CA"
                    },
                    "name": "GST",
                    "rateType": "Standard",
                    "rate": 5.00,
                    "amount": "15.20"
                }
            ]
        },
        {
            "sequenceNumber": 2,
            "dateTime": "2016-04-25T18:00:00-0700",
            "reference": "RT1601",
            "description": "Destination Marketing Fee",
            "semanticsCode": "FEE",
            "quantity": 1,
            "total": "4.56"
        },
        {
            "sequenceNumber": 3,
            "dateTime": "2016-04-26T18:00:00-0700",
            "reference": "4071",
            "description": "Hidden Bar and Lounge",
            "semanticsCode": "MINIBAR",
            "quantity": 1,
            "total": "31.55"
        },
        {
            "sequenceNumber": 4,
            "dateTime": "2016-04-26T18:00:00-0700",
            "reference": "RT1601",
            "description": "Room Chrg Retail",
            "semanticsCode": "ROOMRATE",
            "quantity": 1,
            "total": "304.00",
            "taxes": [
                {
                    "authority": {
                        "addressCountry": "CA"
                    },
                    "name": "Hotel Room Tax",
                    "rate": 11.00,
                    "amount": "33.44"
                },
                {
                    "authority": {
                        "addressCountry": "CA"
                    },
                    "name": "GST",
                    "rateType": "Standard",
                    "rate": 5.00,
                    "amount": "15.20"
                }
            ]
        },
        {
            "sequenceNumber": 5,
            "dateTime": "2016-04-26T18:00:00-0700",
            "reference": "RT1601",
            "description": "Destination Marketing Fee",
            "semanticsCode": "FEE",
            "quantity": 1,
            "total": "4.56"
        }
    ]
}

Generated Receipt Image

Hotel Receipt Image

Ground Transport

Receipt Data

{
    "taxInvoice": true,
    "reference": "ADBXTF25",
    "dateTime": "2016-09-29T15:39:46-0700",
    "total": "65.00",
    "taxesTotal": "5.69",
    "subtotal": "59.87",
    "currencyCode": "USD",
    "broker": {
        "name": "ACME Corporation",
        "taxId": "123-21213",
        "location": {
            "name": "Seattle Downtown",
            "number": "C3404",
            "latitude": 47.6097,
            "longitude": -122.3331,
            "internetAddress": "http://www.acmecorporation.com/",
            "emailAddress": "groundtransport@acmecorporation.com",
            "telephoneNumber": "206-000-0000",
            "faxNumber": "",
            "address": {
                "streetAddress": "1 Ground Transport Way",
                "addressLocality": "Seattle",
                "addressRegion": "WA",
                "addressCountry": "US",
                "postalCode": "90001"
            }
        }
    },
    "seller": {
        "name": "John Smith",
        "location": {
            "address": {
                "streetAddress": "225 42nd Ave S",
                "addressLocality": "Seattle",
                "addressRegion": "WA",
                "addressCountry": "US",
                "postalCode": "98103"
            }
        }
    },
    "taxes": [
        {
            "authority": {
                "addressCountry": "US",
                "addressRegion": "WA"
            },
            "name": "Local Sales Tax",
            "rate": 9.50,
            "amount": "5.69"
        }
    ],
    "payments": [
        {
            "amount": "65.00",
            "cardDetail": {
                "cardType": "Visa",
                "creditCardId": "4321",
                "authorizationCode": "AB123654789"
            }
        }
    ],
    "classOfService": "BLACK",
    "startDateTime": "2014-11-10T15:08:24-0500",
    "endDateTime": "2014-11-10T15:39:46-0500",
    "travelDuration": "PT21M22S",
    "pickupLocation": {
        "name": "Key Center Building, Bellevue, WA",
        "latitude": 47.4436655,
        "longitude": -122.2982266,
        "address": {
            "addressCountry": "US"
        }
    },
    "dropoffLocation": {
        "name": "Seattle-Tacoma International Airport, SeaTac, WA",
        "latitude": 47.4489,
        "longitude": -122.3094,
        "address": {
            "addressCountry": "US"
        }
    },
    "distance": {
        "totalDistance": 15.6,
        "unit": "mi"
    },
    "driverNumber": "DFE154-8567",
    "lineItems": [
        {
            "sequenceNumber": 1,
            "reference": "",
            "description": "Base Fare",
            "additionalDescription": "",
            "semanticsCode": "FEE",
            "quantity": 1,
            "total": "6.39",
            "taxes": [
                {
                    "authority": {
                        "addressCountry": "US",
                        "addressRegion": "WA"
                    },
                    "name": "Local Sales Tax",
                    "rate": 9.50,
                    "amount": "0.61"
                }
            ]
        },
        {
            "sequenceNumber": 2,
            "reference": "",
            "description": "Distance",
            "additionalDescription": "",
            "semanticsCode": "FEE",
            "quantity": 1,
            "total": "49.32",
            "taxes": [
                {
                    "authority": {
                        "addressCountry": "US",
                        "addressRegion": "WA"
                    },
                    "name": "Local Sales Tax",
                    "rate": 9.50,
                    "amount": "4.68"
                }
            ]
        },
        {
            "sequenceNumber": 3,
            "reference": "",
            "description": "Time",
            "additionalDescription": "",
            "semanticsCode": "FEE",
            "quantity": 1,
            "total": "4.16",
            "taxes": [
                {
                    "authority": {
                        "addressCountry": "US",
                        "addressRegion": "WA"
                    },
                    "name": "Local Sales Tax",
                    "rate": 9.50,
                    "amount": "0.40"
                }
            ]
        },
        {
            "sequenceNumber": 4,
            "reference": "",
            "description": "Rounding Down",
            "additionalDescription": "",
            "semanticsCode": "DISCOUNT",
            "quantity": 1,
            "total": "-0.56"
        }
    ]
}

Generated Receipt Image

Ground Transport Receipt Image

Rail (Multiple Tickets)

Receipt Data

{
    "taxInvoice": true,
    "reference": "VDFG4567",
    "dateTime": "2099-11-10T16:04:49-0700",
    "total": "394.00",
    "subtotal": "394.00",
    "taxesTotal": "0.00",
    "currencyCode": "GBP",
    "itineraryLocator": "DSFJKLT4967",
    "seller": {
        "name": "ACME Corporation",
        "description": "",
        "taxId": "321-654321",
        "location": {
            "name": "Headquarters",
            "number": "",
            "latitude": 41.8819,
            "longitude": -87.6278,
            "internetAddress": "http://www.voyages-sncf.com",
            "emailAddress": "info@uk.voyages-sncf.com",
            "telephoneNumber": "0330 822 0333",
            "address": {
                "streetAddress": "34 Tower View",
                "addressLocality": "Kings Hill, WEST MALLING",
                "addressCountry": "GB",
                "postalCode": "ME19 4ED"
            }
        }
    },
    "payments": [
        {
            "amount": "394.00",
            "cardDetail": {
                "cardType": "American Express",
                "creditCardId": "4002"
            }
        }
    ],
    "railTickets": [
        {
            "ticketNumber": "C123456",
            "recordLocator": "AZT222XFT9",
            "issueDateTime": "2015-04-30T12:37:55-0700",
            "passengerName": "John Doe",
            "fare": "197.00",
            "segments": [
                {
                    "departureStation": "Paris Est",
                    "departureDateTime": "2015-11-25T10:00:00-0700",
                    "arrivalStation": "Frankfurt Main HBF",
                    "arrivalDateTime": "2015-11-26T12:00:00+0900",
                    "trainNumber": "9557",
                    "trainType": "TGV",
                    "classOfServiceCode": "First Class",
                    "fare": "98.50"
                },
                {
                    "departureStation": "Frankfurt Main HBF",
                    "departureDateTime": "2015-11-27T10:00:00-0700",
                    "arrivalStation": "Paris Est",
                    "arrivalDateTime": "2015-11-28T12:00:00+0900",
                    "trainNumber": "9558",
                    "trainType": "TGV",
                    "classOfServiceCode": "First Class",
                    "fare": "98.50"
                }
            ]
        },
        {
            "ticketNumber": "C123457",
            "recordLocator": "AZT222XFT9",
            "issueDateTime": "2015-04-30T12:37:55-0700",
            "passengerName": "Jane Doe",
            "fare": "197.00",
            "segments": [
                {
                    "departureStation": "Paris Est",
                    "departureDateTime": "2015-11-25T10:00:00-0700",
                    "arrivalStation": "Frankfurt Main HBF",
                    "arrivalDateTime": "2015-11-26T12:00:00+0900",
                    "trainNumber": "9557",
                    "trainType": "TGV",
                    "classOfServiceCode": "First Class",
                    "fare": "98.50"
                },
                {
                    "departureStation": "Frankfurt Main HBF",
                    "departureDateTime": "2015-11-27T10:00:00-0700",
                    "arrivalStation": "Paris Est",
                    "arrivalDateTime": "2015-11-28T12:00:00+0900",
                    "trainNumber": "9558",
                    "trainType": "TGV",
                    "classOfServiceCode": "First Class",
                    "fare": "98.50"
                }
            ]
        }
    ],
    "lineItems": [
        {
            "sequenceNumber": 1,
            "semanticsCode": "FEE",
            "description": "Credit Card Fee",
            "dateTime": "2015-11-10T16:04:49-0700",
            "subtotal": "4.92",
            "total": "4.92"
        }
    ]
}

Generated Receipt Image

Rail Receipt Image

Response Codes-Receipts

Success Codes

Code Message Information
200 OK Your GET request succeeded.
201 Created Your POST request succeeded. Please note that even though your request passed validation, the service still needs to create your receipt. Because of this processing time, your receipt might not be available for retrieval immediately.
202 Accepted Your request was accepted. Please note that even though your request was accepted, the service still needs to process your receipt. Because of this processing time, your receipt might not be available for retrieval immediately.

Failure Codes

Code Message Response Body Information
400 Bad Request validationErrors JSON object An error occurred while validating your post against the JSON schema. The validationErrors object will contain detailed information about what caused the validation to fail.
Request body could not be parsed This means that the body of your request was empty, or there was an error parsing it.
Link header must be provided and include a URL to a known receipt schema The link header cannot be null or empty, and must include one of the supported receipt type JSON schemas followed by ;rel=describedBy. A list of supported schemas can be retrieved from the /schemas endpoint of this service.
The specified receipt schema is not valid The schema specified in the link header was valid, but an error occurred when the service attempted to fetch the schema internally.
401 Unauthorized User ID in the URL must match the ID in the sub claim of the JWT This response occurs when the JWT used for authentication is valid, but doesn't match the correct user. When using a user JWT, the request must be to a URL for the same user that is represented in the JWT. For more information on the process of obtaining a JWT, see the Authentication service documentation.
403 Forbidden None Authentication failed for some reason. A 403 will be returned if there is no JWT in the Authorization header of the request, or if the JWT is invalid or expired. This response is also for cases where the JWT does not include the scope required to fulfill the request. For more information on JWTs and scopes, see the Authentication service documentation.
404 Not Found None The receipt(s) you requested could not be found. Check that the receipt and/or user ID that you used are correct.
413 Max file size exceeded None The image you posted exceeded the limit of 5MB.
415 Unsupported Media Type Specified Content-Type is not supported The receipt service currently supports receipt data formatted as JSON. The Content-Type header must have the value application/json or the request will fail.
Invalid image type Images must be .png, .jpg, .jpeg, .tiff, or .gif.
500 Internal Server Error Internal error This response is for generic internal server errors. Something went wrong, and we're probably already trying to fix it!
Unable to save receipt into the database An error occurred while trying to update the state of the receipt.
Could not get available receipts An error occurred while trying to fetch receipts for a user by state.

Receipt Image

Image v1

This API has been deprecated.

Partners and customers using a deprecated API should contact SAP Concur and discuss moving to the latest versions.

Learn more in the API Lifecycle & Deprecation Policy.

The SAP Concur Imaging Web service allows clients to manage the receipt images attached to expense reports and the images attached to invoices. Clients can retrieve existing images by reportID, image ID, or invoiceID, and upload new images to a user, expense entry, report, or invoice.

The Imaging web service supports the following image formats:

The maximum file size allowed is 10 MB.

Scope Usage

Name Description Endpoint
IMAGE Add or Retrieve Report and Line Item Images. GET, POST

Product Restrictions

SAP Concur products are highly configurable, and not all clients will have access to all features.

Partner developers must determine which configurations are required for their solution prior to the review process.

Existing clients can work with SAP Concur Advantage Technical Services to create custom applications that work with their configuration.

Post an image

Request

URI

Templates

https://www.concursolutions.com/api/image/v1.0/receipt
https://www.concursolutions.com/api/image/v1.0/expenseentry/{entryId}
https://www.concursolutions.com/api/image/v1.0/invoice/{requestId}
https://www.concursolutions.com/api/image/v1.0/report/{reportId}

Parameters

Required: One of these parameters is always required.

Name Type Format Description
receipt string - Uploads a receipt image and associates it with the OAuth consumer. The user can view the image in the receipt management section of SAP Concur.
entryReceiptID/{entryReceiptId} string - Obtains a short-lived URL (15 minute ttl) that can be rendered to obtain the receipt image.
expenseentry/{entryID} string - Uploads a receipt image and associates it with the expense entry that matches the supplied entry ID. Once an image is attached to the entry, you cannot append additional images.
invoice/{requestID} string - Uploads an invoice image and associates it with the invoice that matches the supplied request ID. Each invoice is uniquely identified by the request ID value. Once an image is attached to the invoice, you cannot append additional images. The Concur Invoice product is required to use this endpoint. Currently you must use the Invoice user interface to get the Request ID value.
report/{reportID} string - Uploads a receipt image and associates it with the report that matches the supplied report ID. If a report image already exists for the report, the new image will be appended to the existing image.

Headers

Payload

A byte array containing the image data.

Response

Status Codes

Headers

Payload

Example

Request

This example contains a truncated (see the ellipsis) 64-bit encoded string representation of the image for illustration purposes only. This example demonstrates one of the endpoints available.

POST https://www.concursolutions.com/api/image/v1.0/receipt
Authorization: OAuth {token}
Content-Length: 65536
Content-Type: image/jpeg
/9j/4AAQSkZJRgABAQEAyADIAAD/2wBDAAgGBgcGBQgHBwcJCQgKDBQNDAsLDBkSEw8UHRofHh0a
HBwgJC4nICIsIxwcKDcpLDAxNDQ0Hyc5PTgyPC4zNDL/2wBDAQkJCQwLDBgNDRgyIRwhMjIyMjIy
MjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjL/wAARCAkiBqQDASIA
AhEBAxEB/8QAHwAAAQUBAQEBAQEAAAAAAAAAAAECAwQFBgcICQoL/8QAtRAAAgEDAwIEAwUFBAQA
AAF9AQIDAAQRBRIhMUEGE1FhByJxFDKBkaEII0KxwRVS0fAkM2JyggkKFhcYGRolJicoKSo0NTY3
ODk6Q0RFRkdISUpTVFVWV1hZWmNkZWZnaGlqc3R1dnd4eXqDhIWGh4iJipKTlJWWl5iZmqKjpKWm
p6ipqrKztLW2t7i5usLDxMXGx8jJytLT1NXW19jZ2uHi4+Tl5ufo6erx8vP09fb3+Pn6/8QAHwEA
AwEBAQEBAQEBAQAAAAAAAAECAwQFBgcICQoL/8QAtREAAgECBAQDBAcFBAQAAQJ3AAECAxEE ...

Response

HTTP/1.1 201 Created
Content-Type: application/xml
<Image xmlns="http://www.concursolutions.com/api/image/2011/02" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
  <Id>aBcDeMwbl34xnwdkUw5ZjDsggDl2$pyoy31$pnGaHAywmPrpbAmE</Id>
  <Url />
</Image>

Get an image URL

Retrieves a URL to the following images:

The URL is valid for 30 minutes after the request.

Request

URI

Template

https://www.concursolutions.com/api/image/v1.0/receipt/{imageId}
https://www.concursolutions.com/api/image/v1.0/expenseentry/{entryId}
https://www.concursolutions.com/api/image/v1.0/invoice/{requestId}
https://www.concursolutions.com/api/image/v1.0/report/{imageId}

Parameters

Name Type Format Description
receipt/{imageId} string - The {keyword}/{identifier} for the desired receipt.
expenseentry/{entryID} string - The {keyword}/{identifier} for the desired expense entry. The entryId is returned in the RpeKey within ExpenseEntry portion of the response from the Expense Report Full Details v1.1 API.
invoice/{requestID} string - The {keyword}/{identifier} for the desired payment request. The Concur Invoice product is required to use this endpoint. Currently you must use the Invoice user interface to get the Request ID value.
report/{imageId} string - The {keyword}/{identifier} for the desired report.

Headers

Payload

None

Response

Status Codes

Headers

Payload

Example

Request

This example demonstrates one of the endpoints available.

GET /api/image/v1.0/expenseentry/A2C40CEE415B43B2A0BE
Authorization: OAuth {token}
Accept: application/xml

Response

200 OK
Content-Type: application/xml
<Image xmlns="http://www.concursolutions.com/api/image/2011/02" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
  <Id>A2C40CEE415B43B2A0BE</Id>
  <Url>https://api.example.com/getImage?cid=able999999&amp;val=F9B35244G86</Url>
</Image>

Schema

Image

The Image schema provides metadata about an image within the system.

Name Type Format Description
Id string - The unique identifier of the image.
Url string - The URL for the image. Note that special characters will be XML-encoded. You will need to unencode any special characters before using the link. This element is empty when uploading images.

C# Code Example

The following example in C# illustrates how to read the source image file as an array of bytes and pass that data into the request.

HttpWebRequest request = (HttpWebRequest)WebRequest.Create(url);
request.Method = "POST";
request.ContentType = "application/pdf";
request.Headers.Add("Authorization", signature);

using (FileStream fs = new FileStream(pathToImageFile, FileMode.Open, FileAccess.Read))
{
    using (BinaryReader br = new BinaryReader(fs))
    {
        byte[] image = br.ReadBytes((int)fs.Length);
        request.ContentLength = image.Length;

        Stream ds = request.GetRequestStream();
        ds.Write(image, 0, image.Length);
        ds.Close();
    }
}

HttpWebResponse webresponse = request.GetResponse();

Receipt Image v3

The SAP Concur Receipt Image API allows for the management of receipt images attached to expense reports, expense entries, and payment requests. You can retrieve existing images by Image ID, and upload new images to a User. This API allows you to upload images in a predefined format and size targeting a specific resource or user in SAP Concur. You can also pull images down from SAP Concur by either displaying them in the browser or downloading the image content to save locally.

Note: This API is not designed to obtain the receipt images attached to an expense report. If you are an Enterprise Partner creating integrations that are intended to obtain final-approved Expense or Invoice data, and the accompanying receipt images that substantiate those transactions you will need to use Image v1. These scenarios include, but are not limited to: ERP integrations for financial journal entry postings, VAT reclaim integrations that obtain transactions to calculate VAT reclaim, project billing integrations used to substantiate expenses billed back, etc.

Receipt Image v3 - Scope Usage

Name Description Endpoint
IMAGE Add or Retrieve Report and Line Item Images. GET, POST, PUT, DELETE

Retrieve a List of All Receipt Images

GET /api/v3.0/expense/receiptimages

Parameters

Name Type Format Description
offset string query Starting page offset
limit Int32 query Number of records to return (default 25)
user string query The login ID of the user. Optional. The user must have the Web Services Admin (Professional) or Can Administer (Standard) user role to use this parameter.

Retrieve a Receipt Image by ID

GET /api/v3.0/expense/receiptimages/{id}

Parameters

Name Type Format Description
id string path Required ReceiptImage ID
user string query The login ID of the user. Optional. The user must have the Web Services Admin (Professional) or Can Administer (Standard) user role to use this parameter.

Example

The above GET request produces this response:

<Image xmlns="http://www.concursolutions.com/api/image/2011/02" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
  <Id>sample</Id>
  <Url>https://imagingupload.concursolutions.com/file/p00884704c6o/5A789811F139BC89D9C42DDE5FEE2A655BB7C2A375E9C481FA0BE92FFF690E298F119925A5C834385C8D62AE5FC4E65AC0F53E4C7273C14A4E71D4264F104882H142570AF84FBEEEC439486FE89E44D2F?id=51253775812C4750888F2e=p00884704c6o3t=AN</Url>
</Image>

Copy and paste the URL into a browser session to render the image. This is a temporary URL.

Create a New Receipt Image

POST /api/v3.0/expense/receiptimages

Parameters

Name Type Format Description
user string query The login ID of the user. Optional. The user must have the Web Services Admin (Professional) or Can Administer (Standard) user role to use this parameter.
image file body Required Image data file

Append a Receipt Image

PUT /api/v3.0/expense/receiptimages/{id}

Parameters

Name Type Format Description
id string path Required ID of the receipt image to update
user string query The login ID of the user. Optional. The user must have the Web Services Admin (Professional) or Can Administer (Standard) user role to use this parameter.
image file body Required Image data file

Delete a Receipt Image

DELETE /api/v3.0/expense/receiptimages/{id}

Parameters

Name Type Format Description
id string path Required ID of the receipt image to delete
user string query The login ID of the user. Optional. The user must have the Web Services Admin (Professional) or Can Administer (Standard) user role to use this parameter.

Receipt Image v3 - Schema

Receipt Images

Name Type Format Description
Items Array Receipt Image The result collection.
NextPage string - The URI of the next page of results, if any.

Receipt Image

Name Type Format Description
ID string - The unique identifier of the resource.
URI string - The URI to the resource.

Request v4

Getting Started - Request v4

Concur Request automates the spend request and approval process for both travel and everyday expenses, giving you the data you need to accurately track and better control spending. By increasing visibility into planned expenses and up-to-date budget data, you can make strategic spending decisions before any spending actually occurs. The Request API provides many possibilities, particularly Requests creation and transition into the approval workflow.

Version 4.0 of Request API works only with the new Authentication API.

Getting Started

Getting Started - Overview

The Request v4 API exposes five different resources:

Resource Description
Request You can read, create, update or delete a Request and get the list of existing Requests.
Workflow You can perform action in the approval workflow of a Request (submit, approve, cancel...)
Expected Expense You can read, create, update or delete an expected expense, and get the list of expected Expenses for a specific Request.
Request Policy You can get the list of existing Request policies.
Travel Agency You can get the description of a Travel Agency office.

These resources are used to manage documents used for pre-spend authorizations within Concur Request.

Getting Started - Prior Versions

Getting Started - Process Flow

Process Flow for Request V4

Getting Started - Products and Editions

Getting Started - Scope Usage

Name Description Endpoint
travelrequest.write Read and write Requests GET, POST, PUT, DELETE

Getting Started - Dependencies

SAP Concur clients must purchase Concur Request in order to use this API. This API may require for some use cases to consume the following additional SAP Concur APIs:

Getting Started - Access Token Usage

This API supports both company level and user level access tokens.

Company Access Token

User Access Token

Request v4 - Request Resources

Request Resources

Create a new Request

Scopes

travelrequest.write - Refer to Scope Usage for full details.

HTTP Request

URI Template

POST {datacenter}/travelrequest/v4/requests

Parameters

Name Type Format Description
userId string - The unique identifier of the Request owner for whom the Request will be created. The corresponding user name will be displayed in the audit trail of the Request. Required when connecting with a Company token, if empty a 400 missingRequiredParam error code will be displayed.

Payload

Request

Since this endpoint is performing a Request creation, specifying an id field in the payload is not allowed.

A newly allocated id value will be returned upon successful Request creation.

HTTP Response

Request Resources - HTTP Status Codes

To learn more about response HTTP status codes for this API see Travel Request v4 - HTTP Status Codes.

Payload

Request - The created Request.

Example

HTTP Request

POST https://us.api.concursolutions.com/travelrequest/v4/requests
Content-Type: application/json
Accept: application/json
Authorization: Bearer {token}
{
  "businessPurpose": "Trip to Lyon for company training",
  "comment": "Company training requires to go to Lyon",
  "custom1": {
    "value": "Training part of IT Service"
  },
  "custom2": {
    "value": "8422A66A9B0142458020D9BCD4351D38"
  },
  "custom3": {
    "value": "5A0F9AF6B92E34468698040C915688BF"
  },
  "custom4": {
    "value": "3F54AE68BA66EF49A5984E5197202A4D"
  },
  "endDate": "2018-07-03",
  "endTime": "22:00",
  "startDate": "2018-07-01",
  "startTime": "07:15",
  "name": "Company Training - JULY 2018",
  "mainDestination": {
    "city": "Lyon, FRANCE",
    "countryCode": "FR",
    "countrySubDivisionCode": "FR-69",
    "name": "Lyon, FRANCE"
  },
  "policy": {
    "id": "F4C8BD31CA9D4D6292795BE687EB9B2A"
  },
  "travelAgency": {
    "id": "2EC038D7C3CBBE4ABA0914425064D34F"
  }
}

HTTP Response

201 Created
{
  "href": "https://us.api.concursolutions.com/travelrequest/v4/requests/CED5E9CD8FC1424488F9331ACF956E73",
  "id": "CED5E9CD8FC1424488F9331ACF956E73",
  "approvalStatus": {
    "code": "NOT_SUBMITTED",
    "name": "Not Submitted"
  },
  "approved": false,
  "businessPurpose": "Trip to Lyon for company training",
  "canceledPostApproval": false,
  "closed": false,
  "comment": "Company training requires to go to Lyon",
  "creationDate": "2018-05-25T08:08:59.000Z",
  "custom1": {
    "value": "Training part of IT Service"
  },
  "custom2": {
    "code": "CEN3",
    "value": "8422A66A9B0142458020D9BCD4351D38"
  },
  "custom3": {
    "code": "CEN3PRO1",
    "value": "5A0F9AF6B92E34468698040C915688BF"
  },
  "custom4": {
    "code": "TRAINING",
    "value": "3F54AE68BA66EF49A5984E5197202A4D"
  },
  "endDate": "2018-07-03",
  "endTime": "22:00",
  "everSentBack": false,
  "expenses": [],
  "highestExceptionLevel": "WARNING",
  "lastModified": "2018-05-25T08:08:59.000Z",
  "mainDestination": {
    "countryCode": "FR",
    "countrySubDivisionCode": "FR-69",
    "city": "Lyon, FRANCE",
    "name": "Lyon, FRANCE"
  },
  "name": "Company Training - JULY 2018",
  "owner": {
    "firstName": "John",
    "id": "c0d9894b-98e2-48d5-86f9-1decde90dd15",
    "lastName": "Doe"
  },
  "pendingApproval": false,
  "policy": {
    "id": "F4C8BD31CA9D4D6292795BE687EB9B2A"
  },
  "requestId": "333U",
  "startDate": "2018-07-01",
  "startTime": "07:15",
  "totalApprovedAmount": {
    "value": 0,
    "currency": "USD"
  },
  "totalPostedAmount": {
    "value": 0,
    "currency": "USD"
  },
  "totalRemainingAmount": {
    "value": 0,
    "currency": "USD"
  },
  "travelAgency": {
    "href": "https://us.api.concursolutions.com/travelrequest/v4/travelagencies/2EC038D7C3CBBE4ABA0914425064D34F",
    "id": "2EC038D7C3CBBE4ABA0914425064D34F",
    "template": "https://https://us.api.concursolutions.com/travelrequest/v4/travelagencies/{id}"
  },
  "type": {
    "code": "TRAVEL",
    "label": "Travel"
  },
  "operations": [
    {
      "rel": "submit",
      "href": "https://us.api.concursolutions.com/travelrequest/v4/requests/CED5E9CD8FC1424488F9331ACF956E73/submit"
    }
  ]
}

Request Resources - Get the list of existing Requests

Scopes

travelrequest.write - Refer to Scope Usage for full details.

HTTP Request

URI Template

GET {datacenter}/travelrequest/v4/requests

Parameters

Name Type Format Description
view string - Name of the view defining the scope of the Requests to get. Supported values:ALL: Get all existing Requests for a user (relevant only for the traveler).
ACTIVEGet all active Requests. Does not include cancelled Requests. Approved Requests included are aged less than three months based on current date and must not be in closed status.
UNSUBMITTED: Get all the unsubmitted Requests (relevant only for the traveler).
PENDING: Get all the Requests that are submitted but not yet approved (relevant only for the traveler).
VALIDATED: Get all the approved Requests for a user (relevant only for the traveler). Closed Requests are included in this view.
APPROVED: Get all the approved Requests by a user (relevant only for the approver). Closed Requests are included in this view.
CANCELED: Get all the cancelled Requests for a user (relevant only for the traveler). Cancelled could include closed/not closed Requests.
CLOSED: Get all the closed Requests for a user (relevant only for the traveler). Includes canceled then closed Request as well as approved then closed Requests.
SUBMITTED: Get all the submitted Requests for a user (relevant only for the traveler). Submitted does not include cancelled requests.
TOAPPROVE: Get all Requests to be approved by the user (relevant only for the approver).
PENDINGEBOOKING: Approved Requests awaiting Concur Travel booking(s).
PENDINGPROPOSAL: Get all Requests submitted to a Travel Agency (TMC) step (relevant only for the TMC agent), userId is required.
PROPOSALAPPROVED: Get all the approved Requests by a user (relevant only for the TMC agent), userId is required.
PROPOSALCANCELED: Get all the cancelled Requests for a user (relevant only for the TMC agent), userId is required.
If no view value is sent, the default view ALL will be used.
userId string - Associated with a traveler view: the unique identifier of the Request owner to use when searching for Requests.
Associated with an approver view: the unique identifier of the approver to user when searching for Requests.
Associated with a TMC agent view, Required, the unique identifier of the TMC agent to use. This TMC agent user must have a default Travel Agency assigned in its profile corresponding to the Travel Agency assigned to the Requests
start integer - Pagination: index of the first record. Default: 0
limit integer - Number of records to return per page. Default: 10. Maximum limit: 100, if higher value or digit value is set, a 400 error code will be displayed.
approvedBefore dateTime yyyy-MM-dd'T'HH:mm:ss.SSS'Z' or yyyy-MM-dd Returns Requests that have been approved before the specified date and time. This search term can be used along with other search terms to narrow the results. The date and time should be in UTC. when time is missing it is defaulted to midnight.
approvedAfter dateTime yyyy-MM-dd'T'HH:mm:ss.SSS'Z' or yyyy-MM-dd Returns Requests that have been approved after the specified date and time. This search term can be used along with other search terms to narrow the results. The date and time should be in UTC. When time is missing it is defaulted to midnight.
modifiedBefore dateTime yyyy-MM-dd'T'HH:mm:ss.SSS'Z' or yyyy-MM-dd Returns Requests in which the associated dependents (Header, Expected expenses, Segments, Allocations, Attendees, Comments) were modified before the specified date and time. This search term can be used along with other search terms to narrow the results. The date and time should be in UTC. When time is missing it is defaulted to midnight.
modifiedAfter dateTime yyyy-MM-dd'T'HH:mm:ss.SSS'Z' or yyyy-MM-dd Returns Requests in which the associated dependents (Header, Expected expenses, Segments, Allocations, Attendees, Comments) were modified after the specified date and time. This search term can be used along with other search terms to narrow the results. The date and time should be in UTC. When time is missing it is defaulted to midnight.
sortField string - The name of the field on which to sort. Supported values: startDate, approvalStatus, requestId. If no view value is sent, the default sortField startDate will be used.
sortOrder string - Sort order. Supported values: ASC, DESC. If no view value is sent, the default sortOrder DESC will be used.

Payload

None.

HTTP Response

Request Resources - HTTP Status Codes

To learn more about response HTTP status codes for this API see Travel Request v4 - HTTP Status Codes.

Payload

List of Request

Example

HTTP Request

GET https://us.api.concursolutions.com/travelrequest/v4/requests?view=ALL&limit=10&start=0
Accept: application/json
Authorization: Bearer {token}

HTTP Response

200 OK
{
  "data": [{
      "href": "https://us.api.concursolutions.com/travelrequest/v4/requests/2B19A2438CD6664A9C44E0F4D39E870A",
      "id": "2B19A2438CD6664A9C44E0F4D39E870A",
      "approvalStatus": {
        "code": "SUBMITTED",
        "name": "Submitted & Pending Approval"
      },
      "approved": false,
      "approver": {
        "id": "86ac9588-5032-3fa7-b3cc-20e97d2d7146",
        "firstName": "Jason",
        "lastName": "McCafee"
      },
      "businessPurpose": "PMP Training in Nantes",
      "canceledPostApproval": false,
      "closed": false,
      "comment": "Plane too early in the morning, if possible book Hotel and arrive the day before\n",
      "creationDate": "2018-09-03T11:53:02.000Z",
      "endDate": "2018-10-08",
      "everSentBack": true,
      "expenses": [],
      "name": "PMP Training - OCTOBER",
      "owner": {
        "firstName": "John",
        "id": "c0d9894b-98e2-48d5-86f9-1decde90dd15",
        "lastName": "Doe"
      },
      "pendingApproval": true,
      "requestId": "3AT7",
      "startDate": "2018-10-08",
      "startTime": "05:00",
      "submitDate": "2018-09-03T11:55:00.000Z",
      "totalApprovedAmount": {
        "value": 213.06,
        "currency": "USD"
      },
      "totalPostedAmount": {
        "value": 213.06,
        "currency": "USD"
      },
      "totalRemainingAmount": {
        "value": 213.06,
        "currency": "USD"
      },
      "type": {
        "code": "TRAVEL",
          "label": "Travel"
      }
    },
    {
      "href": "https://us.api.concursolutions.com/travelrequest/v4/requests/4CCBAE73F3E14346AE93253480F5C409",
      "id": "4CCBAE73F3E14346AE93253480F5C409",
      "approvalStatus": {
        "code": "NOT_SUBMITTED",
        "name": "Not Submitted"
      },
      "approved": false,
      "businessPurpose": "Client meeting for project KIWI",
      "canceledPostApproval": false,
      "closed": false,
      "comment": "Need to arrive the day before as meeting is in Company office early in the morning\n",
      "creationDate": "2018-09-03T11:44:10.000Z",
      "endDate": "2018-09-20",
      "everSentBack": false,
      "expenses": [],
      "name": "Client meeting in Berlin",
      "owner": {
        "firstName": "John",
        "id": "c0d9894b-98e2-48d5-86f9-1decde90dd15",
        "lastName": "Doe"
      },
      "pendingApproval": false,
      "requestId": "3AT6",
      "startDate": "2018-09-18",
      "startTime": "17:30",
      "submitDate": "2018-09-03T11:49:32.000Z",
      "totalApprovedAmount": {
        "value": 478.56,
        "currency": "USD"
      },
      "totalPostedAmount": {
        "value": 478.56,
        "currency": "USD"
      },
      "totalRemainingAmount": {
        "value": 478.56,
        "currency": "USD"
      },
      "type": {
        "code": "TRAVEL",
          "label": "Travel"
      }
    }
  ],
  "operations": [{
      "rel": "next",
      "href": "https://us.api.concursolutions.com/travelrequest/v4/requests?view=ALL&limit=3&start=3"
    },
    {
      "rel": "first",
      "href": "https://us.api.concursolutions.com/travelrequest/v4/requests?view=ALL&limit=3&start=0"
    },
    {
      "rel": "last",
      "href": "https://us.api.concursolutions.com/travelrequest/v4/requests?view=ALL&limit=3&start=135"
    }
  ]
}

Request Resources - Get the content of an existing Request

Scopes

travelrequest.write - Refer to Scope Usage for full details.

HTTP Request

URI Template

GET {datacenter}/travelrequest/v4/requests/{requestUuid}

Parameters

Name Type Format Description
requestUuid string - Required The unique identifier of the Request.
userId string - The unique identifier of the user getting the content of the Request. If empty when using a Company token the default system user will be assumed to perform the action.

Payload

None.

HTTP Response

Request Resources - HTTP Status Codes

To learn more about response HTTP status codes for this API see Travel Request v4 - HTTP Status Codes.

Payload

Request - The Request having {requestUuid} as unique identifier.

Example

HTTP Request

GET https://us.api.concursolutions.com/travelrequest/v4/requests/224AF3CDCC2A5244A37C72FA5770C6F2
Accept: application/json
Authorization: Bearer {token}

HTTP Response

200 OK
{
  "href": "https://us.api.concursolutions.com/travelrequest/v4/requests/224AF3CDCC2A5244A37C72FA5770C6F2",
  "id": "224AF3CDCC2A5244A37C72FA5770C6F2",
  "approvalStatus": {
    "code": "NOT_SUBMITTED",
    "name": "Not Submitted"
  },
  "approved": false,
  "businessPurpose": "Client meeting for project KIWI",
  "canceledPostApproval": false,
  "cashAdvances": {
    "href": "https://us.api.concursolutions.com/travelrequest/v4/requests/224AF3CDCC2A5244A37C72FA5770C6F2/cashadvances",
    "id": "224AF3CDCC2A5244A37C72FA5770C6F2",
    "template": "https://us.api.concursolutions.com/travelrequest/v4/requests/{id}/cashadvances"
  },
  "closed": false,
  "comment": "Need to arrive the day before for meeting in Company Office",
  "comments": {
    "href": "http://us.api.concursolutions.com/travelrequest/v4/requests/224AF3CDCC2A5244A37C72FA5770C6F2/comments",
    "id": "224AF3CDCC2A5244A37C72FA5770C6F2",
    "template": "http://us.api.concursolutions.com/travelrequest/v4/requests/{id}/comments"
  },
  "creationDate": "2018-05-25T07:31:33.000Z",
  "custom1": {
    "value": "Kick-off meeting for project KIWI"
  },
  "custom2": {
    "code": "CEN1",
    "value": "54F0CBD8833CB348BD45A6C7C621C951"
  },
  "custom3": {
    "code": "CEN1PRO2",
    "value": "441D6FC50766A044ACC07FF780F1BAD9"
  },
  "custom4": {
    "code": "CLIENTPROJECT",
    "value": "050BE16A7BF72948810AFDBC9069BD8E"
  },
  "endDate": "2018-07-17",
  "endTime": "19:30",
  "everSentBack": false,
  "exceptions": {
    "href": "https://us.api.concursolutions.com/travelrequest/v4/requests/224AF3CDCC2A5244A37C72FA5770C6F2/exceptions",
    "id": "224AF3CDCC2A5244A37C72FA5770C6F2",
    "template": "https://us.api.concursolutions.com/travelrequest/v4/requests/{id}/exceptions"
  },
  "expensePolicy": {
    "id": "A6D42A825114472FAF402180E20B3751"
  },
  "expenses": [
    {
      "href": "https://us.api.concursolutions.com/travelrequest/v4/expenses/B5FB8991E390474E875D6FD5BB1FDAF1",
      "id": "B5FB8991E390474E875D6FD5BB1FDAF1",
      "template": "https://us.api.concursolutions.com/travelrequest/v4/expenses/{id}"
    },
    {
      "href": "https://us.api.concursolutions.com/travelrequest/v4/expenses/D65BDBD5D980F6498D67A92B06A457B0",
      "id": "D65BDBD5D980F6498D67A92B06A457B0",
      "template": "hhttps://us.api.concursolutions.com/travelrequest/v4/expenses/{id}"
    },
    {
      "href": "https://us.api.concursolutions.com/travelrequest/v4/expenses/C286A46A2DDF984EA28E41CEA278667D",
      "id": "C286A46A2DDF984EA28E41CEA278667D",
      "template": "https://us.api.concursolutions.com/travelrequest/v4/expenses/{id}"
    }
  ],
  "lastModified": "2018-05-25T07:34:01.000Z",
  "mainDestination": {
    "countryCode": "DE",
    "countrySubDivisionCode": "DE-BE",
    "city": "Berlin, GERMANY",
    "name": "Berlin, GERMANY"
  },
  "name": "Client meeting in Berlin - JULY",
  "owner": {
    "firstName": "John",
    "id": "c0d9894b-98e2-48d5-86f9-1decde90dd15",
    "lastName": "Doe"
  },
  "pendingApproval": false,
  "policy": {
    "id": "00497B95D8055849A1B217C8D05FFB86"
  },
  "requestId": "333T",
  "startDate": "2018-07-15",
  "startTime": "06:00",
  "totalApprovedAmount": {
    "value": 494.56,
    "currency": "USD"
  },
  "totalPostedAmount": {
    "value": 494.56,
    "currency": "USD"
  },
  "totalRemainingAmount": {
    "value": 494.56,
    "currency": "USD"
  },
  "travelAgency": {
    "href": "https://us.api.concursolutions.com/travelrequest/v4/travelagencies/2EC038D7C3CBBE4ABA0914425064D34F",
    "id": "2EC038D7C3CBBE4ABA0914425064D34F",
    "template": "https://us.api.concursolutions.com/travelrequest/v4/travelagencies/{id}"
  },
  "type": {
    "code": "TRAVEL",
    "label": "Travel"
  },
  "operations": [
    {
      "rel": "submit",
      "href": "https://us.api.concursolutions.com/travelrequest/v4/requests/224AF3CDCC2A5244A37C72FA5770C6F2/submit"
    }
  ]
}

Request Resources - Update the content of an existing Request

Update of the following fields is supported : comment, startDate, startTime, endDate, endTime, expensePolicy, name, businessPurpose, mainDestination, travelAgency, and custom fields. Other fields will be ignored.

This endpoint supports partial update. You may submit only the fields to update in the body, fields not present in the body will remain unchanged. To clear a field use the value null (without quotes).

id field is not mandatory in the payload, if provided the value must match the requestUuid parameter.

Scopes

travelrequest.write - Refer to Scope Usage for full details.

HTTP Request

URI Template

PUT {datacenter}/travelrequest/v4/requests/{requestUuid}

Parameters

Name Type Format Description
requestUuid string - Required The unique identifier of the Request.
userId string - The unique identifier of the user performing the update. Required when connecting with a Company token. If empty a 400, missingRequiredParam error code will be displayed.

Payload

Request

HTTP Response

Request Resources - HTTP Status Codes

To learn more about response HTTP status codes for this API see Travel Request v4 - HTTP Status Codes.

Payload

Request - The Request having {requestUuid} as unique identifier after update.

Example

HTTP Request

PUT https://us.api.concursolutions.com/travelrequest/v4/requests/E82B0B803671004B9A5D952F34FBD01E
Content-Type: application/json
Accept: application/json
Authorization: Bearer {token}
{
  "businessPurpose": "Trip to Lyon for company training - Modification of dates and Cost center + Custom Field",
  "comment": "Company training requires to go to Lyon - Dates and service changed",
  "custom1": {
    "value": "Training part of IT Service"
  },
  "custom2": {
    "value": "54F0CBD8833CB348BD45A6C7C621C951"
  },
  "custom3": {
    "value": "441D6FC50766A044ACC07FF780F1BAD9"
  },
  "custom4": {
    "value": "3F54AE68BA66EF49A5984E5197202A4D"
  },
  "endDate": "2018-07-09",
  "endTime": "19:00",
  "id": "053A479B3C9DD847B02A203C657AE26B",
  "startDate": "2018-07-07",
  "startTime": "06:15",
  "name": "Company Training - JULY 2018",
  "mainDestination": {
    "city": "Lyon, FRANCE",
    "countryCode": "FR",
    "countrySubDivisionCode": "FR-69",
    "name": "Lyon, FRANCE"
  },
  "policy": {
    "id": "F4C8BD31CA9D4D6292795BE687EB9B2A"
  },
  "travelAgency": {
    "id": "2EC038D7C3CBBE4ABA0914425064D34F"
  }
}

HTTP Response

200 OK
{
  "href": "https://us.api.concursolutions.com/travelrequest/v4/requests/053A479B3C9DD847B02A203C657AE26B",
  "id": "053A479B3C9DD847B02A203C657AE26B",
  "approvalStatus": {
    "code": "NOT_SUBMITTED",
    "name": "Not Submitted"
  },
  "approved": false,
  "businessPurpose": "Trip to Lyon for company training - Modification of dates and Cost center + Custom Field",
  "canceledPostApproval": false,
  "closed": false,
  "comment": "Company training requires to go to Lyon - Dates and service changed",
  "creationDate": "2018-05-25T09:17:25.000Z",
  "custom1": {
    "value": "Training part of IT Service"
  },
  "custom2": {
    "code": "CEN1",
    "value": "54F0CBD8833CB348BD45A6C7C621C951"
  },
  "custom3": {
    "code": "CEN1PRO2",
    "value": "441D6FC50766A044ACC07FF780F1BAD9"
  },
  "custom4": {
    "code": "TRAINING",
    "value": "3F54AE68BA66EF49A5984E5197202A4D"
  },
  "endDate": "2018-07-09",
  "endTime": "19:00",
  "everSentBack": false,
  "expenses": [],
  "lastModified": "2018-05-25T09:24:34.000Z",
  "mainDestination": {
    "countryCode": "FR",
    "countrySubDivisionCode": "FR-69",
    "city": "Lyon, FRANCE",
    "name": "Lyon, FRANCE"
  },
  "name": "Company Training - JULY 2018",
  "owner": {
    "firstName": "John",
    "id": "c0d9894b-98e2-48d5-86f9-1decde90dd15",
    "lastName": "Doe"
  },
  "pendingApproval": false,
  "policy": {
    "id": "F4C8BD31CA9D4D6292795BE687EB9B2A"
  },
  "requestId": "333X",
  "startDate": "2018-07-07",
  "startTime": "06:15",
  "totalApprovedAmount": {
    "value": 0,
    "currency": "USD"
  },
  "totalPostedAmount": {
    "value": 0,
    "currency": "USD"
  },
  "totalRemainingAmount": {
    "value": 0,
    "currency": "USD"
  },
  "travelAgency": {
    "href": "https://us.api.concursolutions.com/travelrequest/v4/travelagencies/2EC038D7C3CBBE4ABA0914425064D34F",
    "id": "2EC038D7C3CBBE4ABA0914425064D34F",
    "template": "https://us.api.concursolutions.com/travelrequest/v4/travelagencies/{id}"
  },
  "type": {
    "code": "TRAVEL",
    "label": "Travel"
  },
  "operations": [
    {
      "rel": "submit",
      "href": "https://us.api.concursolutions.com/travelrequest/v4/requests/053A479B3C9DD847B02A203C657AE26B/submit"
    }
  ]
}

Request Resources - Delete an existing Request

Scopes

travelrequest.write - Refer to Scope Usage for full details.

HTTP Request

URI Template

DELETE {datacenter}/travelrequest/v4/requests/{requestUuid}

Parameters

Name Type Format Description
requestUuid string - Required The unique identifier of the Request.
userId string - The unique identifier of the user performing the deletion. Required when connecting with a Company token. If empty a 400, missingRequiredParam error code will be displayed.

Payload

None.

HTTP Response

Payload

None.

Example

HTTP Request

DELETE https://us.api.concursolutions.com/travelrequest/v4/requests/0D4DC4589D33AC4B9AF2E8B548C7AD2C
Accept: application/json
Authorization: Bearer {token}

HTTP Response

200 OK
true

Request Resources - Get the list of comments for an existing Request

Scopes

travelrequest.write - Refer to Scope Usage for full details.

HTTP Request

URI Template

GET {datacenter}/travelrequest/v4/requests/{requestUuid}/comments

Parameters

Name Type Format Description
requestUuid string - Required The unique identifier of the Request.

Payload

None.

HTTP Response

Request Resources - HTTP Status Codes

To learn more about response HTTP status codes for this API see Travel Request v4 - HTTP Status Codes.

Payload

Comments

Example

HTTP Request

GET https://us.api.concursolutions.com/travelrequest/v4/requests/224AF3CDCC2A5244A37C72FA5770C6F2/comments
Accept: application/json
Authorization: Bearer {token}

HTTP Response

200 OK
[
  {
    "author": {
      "firstName": "Steve",
      "lastName": "Smith"
    },
    "creationDateTime": "2019-07-12T11:51:14.000Z",
    "isLatest": true,
    "value": "Please specify an amount less than 600 Euros"
  },
  {
    "author": {
      "firstName": "John",
      "lastName": "Doe"
    },
    "creationDateTime": "2019-07-12T11:11:39.000Z",
    "isLatest": false,
    "value": "Please review the business meal excepted expense to confirm required amount"
  }
]

Request Resources - Get the list of cash advances assigned to an existing Request

Scopes

travelrequest.write - Refer to Scope Usage for full details.

HTTP Request

URI Template

GET {datacenter}/travelrequest/v4/requests/{requestUuid}/cashadvances

Parameters

Name Type Format Description
requestUuid string - Required The unique identifier of the Request.
userId string - The unique identifier of the user getting the list of the cash advances assigned to a Request. Required when connecting with a Company token. If empty, a 400 missingRequiredParam error code will be displayed.

Payload

None.

HTTP Response

Request Resources - HTTP Status Codes

To learn more about response HTTP status codes for this API see Travel Request v4 - HTTP Status Codes.

Payload

ResourceLink - The resource link leading to the created cash advance.

Example

HTTP Request

GET https://us.api.concursolutions.com/travelrequest/v4/requests/224AF3CDCC2A5244A37C72FA5770C6F2/cashadvances
Accept: application/json
Authorization: Bearer {token}

HTTP Response

200 OK
[
    {
        "href": "https://us.api.concursolutions.com/travelrequest/v4/cashadvances/EF3E237ACAA3C449B808BA75BDD049FA",
        "id": "EF3E237ACAA3C449B808BA75BDD049FA",
        "template": "https://us.api.concursolutions.com/travelrequest/v4/cashadvances/{id}"
    },
    {
        "href": "https://us.api.concursolutions.com/travelrequest/v4/cashadvances/9DDAB28B89828A4497209062F4AF87D6",
        "id": "9DDAB28B89828A4497209062F4AF87D6",
        "template": "https://us.api.concursolutions.com/travelrequest/v4/cashadvances/{id}"
    }
]

Request Resources - Get the list of exceptions linked to an existing Request

Scopes

travelrequest.write - Refer to Scope Usage for full details.

HTTP Request

URI Template

GET {datacenter}/travelrequest/v4/requests/{requestUuid}/exceptions

Parameters

Name Type Format Description
requestUuid string - Required The unique identifier of the Request.
userId string - The unique identifier of the user getting the content of the exceptions. Required when connecting with a Company token. If empty, a 400 missingRequiredParam error code will be displayed.

Payload

None.

HTTP Response

Request Resources - HTTP Status Codes

To learn more about response HTTP status codes for this API see Travel Request v4 - HTTP Status Codes.

Payload

Exceptions

Example

HTTP Request

GET https://us.api.concursolutions.com/travelrequest/v4/requests/224AF3CDCC2A5244A37C72FA5770C6F2/exceptions
Accept: application/json
Authorization: Bearer {token}

HTTP Response

200 OK
[
    {
        "code": "CALWARN2",
        "level": 1,
        "message": "The requested Cash Advance exceeds the limit allowed by your company policy which is defined as the total of Daily Allowances (€0.00). Please update the requested amount accordingly.",
        "isBlocking": false,
        "source": {
            "id": "DAF37B097DB82D4D9A15E9F3F7E460C9",
            "href": "https://emea.api.concursolutions.com/v4/requests/DAF37B097DB82D4D9A15E9F3F7E460C9?compact=false",
            "type": "HEADER"
        },
        "parameters": {}
    }
]

Request v4 - Workflow Resources

Workflow Resources

Manage workflow transitions for a Request.

Move an existing Request in the approval workflow

Scopes

travelrequest.write - Refer to Scope Usage for full details.

HTTP Request

The HATEOAS links for actions available given the current user and state are listed in the operations of the Request resource.

Traveler actions * submit: initiate the approval workflow. * recall: get back the Request, usually to modify the content. * cancel: cancel the Request and attached itineraries. * close: archive the Request. * reopen: get back an archived Request.

Non traveler actions (Approver / Processor / External Validation / TMC Agent)

URI Template
POST {datacenter}/travelrequest/v4/requests/{requestUuid}/{action}

Parameters

Name Type Format Description
requestUuid string - Required The unique identifier of the Request.
action string - Required The state transition to be executed. Supported values: submit, approve, recall, sendback, cancel, close, or reopen
comment string - Only works with when the workflow action is sendback. This comment is visible wherever Request comments are available to the employee, approver, and/or Request administrator.
userId string - The unique identifier of the user performing the status transition. Required when connecting with a Company token for traveler actions only. If empty, a 400 missingRequiredParam error code will be displayed. For non traveler actions, if not provided, "System, Concur" will be displayed in the Audit Trail of the Request.
companyID string - The unique identifier of the company.

Payload

None, except when the workflow action is sendback where an optional comment may be submitted

{ "comment" : "My Comment" }

This comment is visible wherever Request comments are available to the employee, approver, and/or Request administrator.

HTTP Response

v4 Endpoints Workflow - HTTP Status Codes

To learn more about response HTTP status codes for this API see Travel Request v4 - HTTP Status Codes.

Payload

Request - The Request having {requestUuid} as unique identifier.

Example

HTTP Request

POST https://us.api.concursolutions.com/travelrequest/v4/requests/053A479B3C9DD847B02A203C657AE26B/submit
Content-Type: application/json
Accept: application/json
Authorization: Bearer {token}

HTTP Response

200 OK
{
  "href": "https://us.api.concursolutions.com/travelrequest/v4/requests/053A479B3C9DD847B02A203C657AE26B",
  "id": "053A479B3C9DD847B02A203C657AE26B",
  "approvalStatus": {
    "code": "SUBMITTED",
    "name": "Submitted & Pending Approval"
  },
  "approved": false,
  "businessPurpose": "Trip to Lyon for company training - Modification of dates and Cost center + Custom Field",
  "canceledPostApproval": false,
  "closed": false,
  "creationDate": "2018-05-25T09:17:25.000Z",
  "custom1": {
    "value": "Training part of IT Service"
  },
  "custom2": {
    "code": "CEN1",
    "value": "54F0CBD8833CB348BD45A6C7C621C951"
  },
  "custom3": {
    "code": "CEN1PRO2",
    "value": "441D6FC50766A044ACC07FF780F1BAD9"
  },
  "custom4": {
    "code": "TRAINING",
    "value": "3F54AE68BA66EF49A5984E5197202A4D"
  },
  "endDate": "2018-07-09",
  "endTime": "19:00",
  "everSentBack": false,
  "expenses": [
    {
      "href": "https://us.api.concursolutions.com/travelrequest/v4/expenses/47C8AD9E382B5143BB54DC3090577C60",
      "id": "47C8AD9E382B5143BB54DC3090577C60",
      "template": "https://us.api.concursolutions.com/travelrequest/v4/expenses/{id}"
    }
  ],
  "lastModified": "2018-05-25T09:38:02.000Z",
  "mainDestination": {
    "countryCode": "FR",
    "countrySubDivisionCode": "FR-69",
    "city": "Lyon, FRANCE",
    "name": "Lyon, FRANCE"
  },
  "name": "Company Training - JULY 2018",
  "owner": {
    "firstName": "John",
    "id": "c0d9894b-98e2-48d5-86f9-1decde90dd15",
    "lastName": "Doe"
  },
  "pendingApproval": true,
  "policy": {
    "id": "F4C8BD31CA9D4D6292795BE687EB9B2A"
  },
  "requestId": "333X",
  "startDate": "2018-07-07",
  "startTime": "06:15",
  "submitDate": "2018-05-25T09:38:02.000Z",
  "totalApprovedAmount": {
    "value": 123.56,
    "currency": "USD"
  },
  "totalPostedAmount": {
    "value": 123.56,
    "currency": "USD"
  },
  "totalRemainingAmount": {
    "value": 123.56,
    "currency": "USD"
  },
  "travelAgency": {
    "href": "https://us.api.concursolutions.com/travelrequest/v4/travelagencies/2EC038D7C3CBBE4ABA0914425064D34F",
    "id": "2EC038D7C3CBBE4ABA0914425064D34F",
    "template": "https://us.api.concursolutions.com/travelrequest/v4/travelagencies/{id}"
  },
  "operations": [
    {
      "rel": "recall",
      "href": "https://us.api.concursolutions.com/travelrequest/v4/requests/053A479B3C9DD847B02A203C657AE26B/recall"
    },
    {
      "rel": "cancel",
      "href": "https://us.api.concursolutions.com/travelrequest/v4/requests/053A479B3C9DD847B02A203C657AE26B/cancel"
    }
  ]
}

Request v4 - Expected Expense Resources

Expected Expense Resources

Manage expected expenses attached to a Request.

Create a new expected expense

Scopes

travelrequest.write - Refer to Scope Usage for full details.

HTTP Request

URI Template

POST {datacenter}/travelrequest/v4/requests/{requestUuid}/expenses

Parameters

Name Type Format Description
requestUuid string - Required The unique identifier of the Request to which the expected expense is attached.
userId string - The unique identifier of the user performing the expected expense creation. Required when connecting with a Company token. If empty, a 400 missingRequiredParam error code will be displayed.

Payload

Expected Expense

HTTP Response

v4 Expected Expense - HTTP Status Codes

To learn more about response HTTP status codes for this API see Travel Request v4 - HTTP Status Codes.

Payload

Expected Expense - The created expected expense.

Example

HTTP Request

POST https://us.api.concursolutions.com/travelrequest/v4/requests/224AF3CDCC2A5244A37C72FA5770C6F2/expenses
Content-Type: application/json
Accept: application/json
Authorization: Bearer {token}
{
  "allocations": [
    {
      "allocationAmount": {
        "currency": "USD",
        "value": 122.38
      },
      "approvedAmount": {
        "currency": "USD",
        "value": 122.38
      },
      "percentEdited": false,
      "percentage": 0,
      "postedAmount": {
        "currency": "USD",
        "value": 122.38
      },
      "systemAllocation": false
    }
  ],
  "approvedAmount": {
    "currency": "USD",
    "value": 122.38
  },
  "businessPurpose": "additional punctual trip to South of France",
  "exchangeRate": {
    "operation": "MULTIPLY",
    "value": 1
  },
  "expenseType": {
    "id": "RAILF",
    "name": "Train"
  },
  "lastComment": "",
  "location": {
    "id": "A168CDBA58AE42868961BC00278A91B3",
    "countryCode": "FR",
    "countrySubDivisionCode": "FR-75",
    "city": "Paris",
    "name": "Charles De Gaulle Intl"
  },
  "postedAmount": {
    "currency": "USD",
    "value": 122.38
  },
  "remainingAmount": {
    "currency": "USD",
    "value": 122.38
  },
  "transactionAmount": {
    "currency": "USD",
    "value": 122.38
  },
  "transactionDate": "2018-07-18T00:00:00Z",
  "tripData": {
    "agencyBooked": false,
    "legs": [
      {
        "class": {
          "code": "1ST",
          "value": "05F71FA4ED235D479C6C7039F397DA79"
        },
        "endLocation": {
          "countryCode": "FR",
          "locationCode": "FRNCE",
          "city": "Nice",
          "name": "Cote D Azur"
        },
        "returnLeg": false,
        "startDate": "2018-07-18",
        "startLocation": {
          "countryCode": "FR",
          "locationCode": "FRCDG",
          "city": "Paris",
          "name": "ROISSY"
        },
        "startTime": "21:00",
        "startLocationDetail": "none"
      }
    ],
    "segmentType": {
      "category": "REQ_SEG_RAILF",
      "code": "RAILF"
    },
    "selfBooked": false,
    "tripType": "ONE_WAY"
  }
}

HTTP Response

201 Created
{
  "href": "https://us.api.concursolutions.com/travelrequest/v4/expenses/0465224E14C23D4F8C2BC79A9D694BDD",
  "id": "0465224E14C23D4F8C2BC79A9D694BDD",
  "allocations": [
    {
      "allocationAmount": {
        "value": 122.38,
        "currency": "USD"
      },
      "approvedAmount": {
        "value": 122.38,
        "currency": "USD"
      },
      "allocationId": "28E1B1F50253CD47BE002DA7B2C218EE",
      "postedAmount": {
        "value": 122.38,
        "currency": "USD"
      },
      "expenseId": "0465224E14C23D4F8C2BC79A9D694BDD",
      "percentEdited": false,
      "systemAllocation": true,
      "percentage": 100
    }
  ],
  "approvedAmount": {
    "value": 122.38,
    "currency": "USD"
  },
  "exchangeRate": {
    "value": 1,
    "operation": "MULTIPLY"
  },
  "expenseType": {
    "id": "TRAIN",
    "name": "Train"
   },
  "postedAmount": {
    "value": 122.38,
    "currency": "USD"
  },
  "remainingAmount": {
    "value": 122.38,
    "currency": "USD"
  },
  "transactionAmount": {
    "value": 122.38,
    "currency": "USD"
  },
  "transactionDate": "2018-07-18T00:00:00.000Z",
  "tripData": {
    "agencyBooked": false,
    "selfBooked": false,
    "tripType": "ONE_WAY",
    "legs": [
      {
        "class": {
          "code": "1ST",
          "value": "05F71FA4ED235D479C6C7039F397DA79"
        },
        "endLocation": {
          "id": "CE4A6DCAC4A14D08803C28F6D5CB20F0",
          "countryCode": "FR",
          "countrySubDivisionCode": "FR-06",
          "name": "Nice",
          "locationCode": "IATA_NCE",
          "locationType": "STD"
        },
        "id": "59508E1F979B4346AC6B38677ABE6404",
        "returnLeg": false,
        "startDate": "2018-07-18",
        "startLocation": {
          "id": "A168CDBA58AE42868961BC00278A91B3",
          "countryCode": "FR",
          "countrySubDivisionCode": "FR-75",
          "name": "Paris",
          "locationCode": "IATA_CDG",
          "locationType": "STD"
        },
        "startLocationDetail": "none",
        "startTime": "21:00"
      }
    ],
    "segmentType": {
      "category": "REQ_SEG_RAILF",
      "code": "RAILF"
    }
  }
}

Get the list of expected expenses attached to a Request

Scopes

travelrequest.write - Refer to Scope Usage for full details.

HTTP Request

URI Template

GET {datacenter}/travelrequest/v4/requests/{requestUuid}/expenses

Parameters

Name Type Format Description
requestUuid string - Required The unique identifier of the Request.
userId string - The unique identifier of the user viewing the expected expenses attached to a Request. If empty when using a Company token the default system user will be assumed to perform the action.

Payload

None.

HTTP Response

v4 Expected Expense - HTTP Status Codes

To learn more about response HTTP status codes for this API see Travel Request v4 - HTTP Status Codes.

Payload

Expected Expense - List of expected expenses attached to a Request.

operations - [RFC 5988] Pagination links to next/prev/first/last page.

Example

HTTP Request

GET https://us.api.concursolutions.com/travelrequest/v4/requests/224AF3CDCC2A5244A37C72FA5770C6F2/expenses
Accept: application/json
Authorization: Bearer {token}

HTTP Response

200 OK
[
  {
    "href": "https://us.api.concursolutions.com/travelrequest/v4/expenses/B5FB8991E390474E875D6FD5BB1FDAF1",
    "id": "B5FB8991E390474E875D6FD5BB1FDAF1",
    "allocations": [
      {
        "allocationAmount": {
          "value": 324.56,
          "currency": "USD"
        },
        "approvedAmount": {
          "value": 324.56,
          "currency": "USD"
        },
        "allocationId": "79249903DC18464AAAD61062EA383BD4",
        "postedAmount": {
          "value": 324.56,
          "currency": "USD"
        },
        "expenseId": "B5FB8991E390474E875D6FD5BB1FDAF1",
        "percentEdited": false,
        "systemAllocation": true,
        "percentage": 100
      }
    ],
    "approvedAmount": {
      "value": 324.56,
      "currency": "USD"
    },
    "exchangeRate": {
      "value": 1,
      "operation": "MULTIPLY"
    },
    "expenseType": {
      "id": "AIRFR",
      "name": "Airfare"
    },
    "postedAmount": {
      "value": 324.56,
      "currency": "USD"
    },
    "remainingAmount": {
      "value": 324.56,
      "currency": "USD"
    },
    "transactionAmount": {
      "value": 324.56,
      "currency": "USD"
    },
    "transactionDate": "2018-07-15T00:00:00.000Z",
    "tripData": {
      "agencyBooked": true,
      "selfBooked": false,
      "tripType": "ROUND_TRIP",
      "legs": [
        {
        "class": {
          "code": "1ST",
          "value": "05F71FA4ED235D479C6C7039F397DA79"
        },
          "endLocation": {
            "id": "4A33695120254EEC9261B24993DD413B",
            "countryCode": "DE",
            "countrySubDivisionCode": "DE-BE",
            "city": "Berlin",
            "iataCode": "BER",
            "name": "Berlin(Alls)"
          },
          "id": "B0F356643B38BC419AFE60E050BB79A4",
          "returnLeg": false,
          "startDate": "2018-07-15",
          "startLocation": {
            "id": "A168CDBA58AE42868961BC00278A91B3",
            "countryCode": "FR",
            "countrySubDivisionCode": "FR-75",
            "city": "Paris",
            "iataCode": "CDG",
            "name": "Charles De Gaulle Intl"
          },
          "startTime": "08:00"
        },
        {
          "endLocation": {
            "id": "A168CDBA58AE42868961BC00278A91B3",
            "countryCode": "FR",
            "countrySubDivisionCode": "FR-75",
            "city": "Paris",
            "iataCode": "CDG",
            "name": "Charles De Gaulle Intl"
          },
          "id": "345475D42A53D948A6D60181759683E8",
          "returnLeg": true,
          "startDate": "2018-07-17",
          "startLocation": {
            "id": "4A33695120254EEC9261B24993DD413B",
            "countryCode": "DE",
            "countrySubDivisionCode": "DE-BE",
            "city": "Berlin",
            "iataCode": "BER",
            "name": "Berlin(Alls)"
          },
          "startTime": "17:00"
        }
      ],
      "segmentType": {
        "category": "REQ_SEG_AIRFR",
        "code": "AIRFR"
      }
    }
  },
  {
    "href": "https://us.api.concursolutions.com/travelrequest/v4/expenses/D65BDBD5D980F6498D67A92B06A457B0",
    "id": "D65BDBD5D980F6498D67A92B06A457B0",
    "allocations": [
      {
        "allocationAmount": {
          "value": 90,
          "currency": "USD"
        },
        "approvedAmount": {
          "value": 90,
          "currency": "USD"
        },
        "allocationId": "FCAA998834A24949B01AC3C1D56AF4E3",
        "postedAmount": {
          "value": 90,
          "currency": "USD"
        },
        "expenseId": "D65BDBD5D980F6498D67A92B06A457B0",
        "percentEdited": false,
        "systemAllocation": true,
        "percentage": 100
      }
    ],
    "approvedAmount": {
      "value": 90,
      "currency": "USD"
    },
    "businessPurpose": "Airport to Office after arrival and before departure",
    "exchangeRate": {
      "value": 1,
      "operation": "MULTIPLY"
    },
    "expenseType": {
      "id": "TAXIX",
      "name": "Taxi"
    },
    "location": {
      "id": "34AB34319377456B95F5C2815CC72766",
      "countryCode": "DE",
      "countrySubDivisionCode": "DE-BER",
      "city": "Berlin, GERMANY",
      "name": "Berlin, GERMANY"
    },
    "postedAmount": {
      "value": 90,
      "currency": "USD"
    },
    "remainingAmount": {
      "value": 90,
      "currency": "USD"
    },
    "transactionAmount": {
      "value": 90,
      "currency": "USD"
    },
    "transactionDate": "2018-07-17T00:00:00.000Z"
  },
  {
    "href": "https://us.api.concursolutions.com/travelrequest/v4/expenses/C286A46A2DDF984EA28E41CEA278667D",
    "id": "C286A46A2DDF984EA28E41CEA278667D",
    "allocations": [
      {
        "allocationAmount": {
          "value": 80,
          "currency": "USD"
        },
        "approvedAmount": {
          "value": 80,
          "currency": "USD"
        },
        "allocationId": "780B3FA5B83EC24F922EBE7B5D4AED63",
        "postedAmount": {
          "value": 80,
          "currency": "USD"
        },
        "expenseId": "C286A46A2DDF984EA28E41CEA278667D",
        "percentEdited": false,
        "systemAllocation": true,
        "percentage": 100
      }
    ],
    "approvedAmount": {
      "value": 80,
      "currency": "USD"
    },
    "businessPurpose": "Estimated costs for 2 dinners in Berlin",
    "exchangeRate": {
      "value": 1,
      "operation": "MULTIPLY"
    },
    "expenseType": {
      "id": "DINNR",
      "name": "Dinner"
    },
    "location": {
      "id": "34AB34319377456B95F5C2815CC72766",
      "countryCode": "DE",
      "countrySubDivisionCode": "DE-BER",
      "city": "Berlin, GERMANY",
      "name": "Berlin, GERMANY"
    },
    "postedAmount": {
      "value": 80,
      "currency": "USD"
    },
    "remainingAmount": {
      "value": 80,
      "currency": "USD"
    },
    "transactionAmount": {
      "value": 80,
      "currency": "USD"
    },
    "transactionDate": "2018-07-17T00:00:00.000Z"
  }
]

Get the content of an expected expense

Scopes

travelrequest.write - Refer to Scope Usage for full details.

HTTP Request

URI Template

GET {datacenter}/travelrequest/v4/expenses/{expenseUuid}

Parameters

Name Type Format Description
expenseUuid string - Required The unique identifier of the expected expense.
userId string - The unique identifier of the user viewing the expected expense. If empty when using a Company token the default system user will be assumed to perform the action.

Payload

None.

HTTP Response

v4 Expected Expense - HTTP Status Codes

To learn more about response HTTP status codes for this API see Travel Request v4 - HTTP Status Codes.

Payload

Expected Expense - The expected expense having {expenseUuid} as unique identifier.

Example 1 - for a Request segment

HTTP Request

GET https://us.api.concursolutions.com/travelrequest/v4/expenses/B5FB8991E390474E875D6FD5BB1FDAF1
Accept: application/json
Authorization: Bearer {token}

HTTP Response

200 OK
{
  "href": "https://us.api.concursolutions.com/travelrequest/v4/expenses/B5FB8991E390474E875D6FD5BB1FDAF1",
  "id": "B5FB8991E390474E875D6FD5BB1FDAF1",
  "allocations": [
    {
      "allocationAmount": {
        "value": 324.56,
        "currency": "USD"
      },
      "approvedAmount": {
        "value": 324.56,
        "currency": "USD"
      },
      "allocationId": "79249903DC18464AAAD61062EA383BD4",
      "postedAmount": {
        "value": 324.56,
        "currency": "USD"
      },
      "expenseId": "B5FB8991E390474E875D6FD5BB1FDAF1",
      "percentEdited": false,
      "systemAllocation": true,
      "percentage": 100
    }
  ],
  "approvedAmount": {
    "value": 324.56,
    "currency": "USD"
  },
  "comments": {
    "href": "https://us.api.concursolutions.com/travelrequest/v4/expenses/2F9FB5CE3AC2C74C9AC3D4AB3A83C0DA/comments",
    "id": "2F9FB5CE3AC2C74C9AC3D4AB3A83C0DA",
    "template": "http://us.api.concursolutions.com/travelrequest/v4/expenses/{id}/comments"
  },
  "exchangeRate": {
    "value": 1,
    "operation": "MULTIPLY"
  },
  "expenseType": {
    "id": "AIRFR",
    "name": "Airfare"
  },
  "parentRequest": {
    "href": "https://us.api.concursolutions.com/travelrequest/v4/request/224AF3CDCC2A5244A37C72FA5770C6F2",
    "id": "224AF3CDCC2A5244A37C72FA5770C6F2",
    "template": "http://us.api.concursolutions.com/travelrequest/v4/request/{requestUuid}"
  },
  "postedAmount": {
    "value": 324.56,
    "currency": "USD"
  },
  "remainingAmount": {
    "value": 324.56,
    "currency": "USD"
  },
  "transactionAmount": {
    "value": 324.56,
    "currency": "USD"
  },
  "transactionDate": "2018-07-15T00:00:00.000Z",
  "tripData": {
    "agencyBooked": true,
    "selfBooked": false,
    "tripType": "ROUND_TRIP",
    "legs": [
      {
        "class": {
          "code": "1ST",
          "value": "05F71FA4ED235D479C6C7039F397DA79"
        },
        "endLocation": {
          "id": "4A33695120254EEC9261B24993DD413B",
          "countryCode": "DE",
          "countrySubDivisionCode": "DE-BE",
          "city": "Berlin",
          "iataCode": "BER",
          "name": "Berlin(Alls)"
        },
        "id": "B0F356643B38BC419AFE60E050BB79A4",
        "returnLeg": false,
        "startDate": "2018-07-15",
        "startLocation": {
          "id": "A168CDBA58AE42868961BC00278A91B3",
          "countryCode": "FR",
          "countrySubDivisionCode": "FR-75",
          "city": "Paris",
          "iataCode": "CDG",
          "name": "Charles De Gaulle Intl"
        },
        "startTime": "08:00"
      },
      {
        "endLocation": {
          "id": "A168CDBA58AE42868961BC00278A91B3",
          "countryCode": "FR",
          "countrySubDivisionCode": "FR-75",
          "city": "Paris",
          "iataCode": "CDG",
          "name": "Charles De Gaulle Intl"
        },
        "id": "345475D42A53D948A6D60181759683E8",
        "returnLeg": true,
        "startDate": "2018-07-17",
        "startLocation": {
          "id": "4A33695120254EEC9261B24993DD413B",
          "countryCode": "DE",
          "countrySubDivisionCode": "DE-BE",
          "city": "Berlin",
          "iataCode": "BER",
          "name": "Berlin(Alls)"
        },
        "startTime": "17:00"
      }
    ],
    "segmentType": {
      "category": "REQ_SEG_AIRFR",
      "code": "AIRFR"
    }
  }
}

Example 2 - for a Request expected expense

HTTP Request

GET https://us.api.concursolutions.com/travelrequest/v4/expenses/C286A46A2DDF984EA28E41CEA278667D
Accept: application/json
Authorization: Bearer {token}

HTTP Response

200 OK
{
  "href": "https://us.api.concursolutions.com/travelrequest/v4/expenses/C286A46A2DDF984EA28E41CEA278667D",
  "id": "C286A46A2DDF984EA28E41CEA278667D",
  "allocations": [
    {
      "allocationAmount": {
        "value": 80,
        "currency": "USD"
      },
      "approvedAmount": {
        "value": 80,
        "currency": "USD"
      },
      "allocationId": "780B3FA5B83EC24F922EBE7B5D4AED63",
      "postedAmount": {
        "value": 80,
        "currency": "USD"
      },
      "expenseId": "C286A46A2DDF984EA28E41CEA278667D",
      "percentEdited": false,
      "systemAllocation": true,
      "percentage": 100
    }
  ],
  "approvedAmount": {
    "value": 80,
    "currency": "USD"
  },
  "businessPurpose": "Estimated costs for 2 dinners in Berlin",
  "exchangeRate": {
    "value": 1,
    "operation": "MULTIPLY"
  },
  "expenseType": {
    "id": "DINNR",
    "name": "Dinner"
  },
  "location": {
    "id": "34AB34319377456B95F5C2815CC72766",
    "countryCode": "DE",
    "countrySubDivisionCode": "DE-BER",
    "city": "Berlin, GERMANY",
    "name": "Berlin, GERMANY"
  },
  "parentRequest": {
    "href": "https://us.api.concursolutions.com/travelrequest/v4/request/224AF3CDCC2A5244A37C72FA5770C6F2",
    "id": "224AF3CDCC2A5244A37C72FA5770C6F2",
    "template": "http://us.api.concursolutions.com/travelrequest/v4/request/{requestUuid}"
  },
  "postedAmount": {
    "value": 80,
    "currency": "USD"
  },
  "remainingAmount": {
    "value": 80,
    "currency": "USD"
  },
  "transactionAmount": {
    "value": 80,
    "currency": "USD"
  },
  "transactionDate": "2018-07-17T00:00:00.000Z"
}

Update the content of an expected expense

Scopes

travelrequest.write - Refer to Scope Usage for full details.

HTTP Request

URI Template

PUT {datacenter}/travelrequest/v4/expenses/{expenseUuid}

Parameters

Name Type Format Description
expenseUuid string - Required The unique identifier of the expected expense to update.
userId string - The unique identifier of the user performing the expected expense update. Required when connecting with a Company token. If empty, a 400 missingRequiredParam error code will be displayed.

Payload

Expected Expense

HTTP Response

v4 Expected Expense - HTTP Status Codes

To learn more about response HTTP status codes for this API see Travel Request v4 - HTTP Status Codes.

Payload

Expected Expense - The expected expense having {expenseUuid} as unique identifier after update.

Example

HTTP Request

PUT https://us.api.concursolutions.com/travelrequest/v4/expenses/B5FB8991E390474E875D6FD5BB1FDAF1
Content-Type: application/json
Accept: application/json
Authorization: Bearer {token}
{
  "id": "B5FB8991E390474E875D6FD5BB1FDAF1",
  "allocations": [
    {
      "allocationAmount": {
        "value": 432.45,
        "currency": "USD"
      },
      "approvedAmount": {
        "value": 432.45,
        "currency": "USD"
      },
      "allocationId": "79249903DC18464AAAD61062EA383BD4",
      "postedAmount": {
        "value": 432.45,
        "currency": "USD"
      },
      "expenseId": "B5FB8991E390474E875D6FD5BB1FDAF1",
      "percentEdited": false,
      "systemAllocation": true,
      "percentage": 100
    }
  ],
  "approvedAmount": {
    "value": 432.45,
    "currency": "USD"
  },
  "exchangeRate": {
    "value": 1,
    "operation": "MULTIPLY"
  },
  "expenseType": {
    "id": "AIRFR",
    "name": "Airfare"
  },
  "postedAmount": {
    "value": 432.45,
    "currency": "USD"
  },
  "remainingAmount": {
    "value": 432.45,
    "currency": "USD"
  },
  "transactionAmount": {
    "value": 432.45,
    "currency": "USD"
  },
  "transactionDate": "2018-07-16T00:00:00.000Z",
  "tripData": {
    "agencyBooked": true,
    "selfBooked": false,
    "tripType": "ROUND_TRIP",
    "legs": [
      {
        "class": {
          "code": "1ST",
          "value": "05F71FA4ED235D479C6C7039F397DA79"
        },
        "endLocation": {
          "countryCode": "DE",
          "city": "Berlin",
          "iataCode": "BER",
          "name": "Berlin(Alls)"
        },
        "id": "B0F356643B38BC419AFE60E050BB79A4",
        "returnLeg": false,
        "startDate": "2018-07-16",
        "startLocation": {
          "countryCode": "FR",
          "city": "Paris",
          "iataCode": "CDG",
          "name": "Charles De Gaulle Intl"
        },
        "startTime": "07:00"
      },
      {
        "endLocation": {
          "countryCode": "FR",
          "city": "Paris",
          "iataCode": "CDG",
          "name": "Charles De Gaulle Intl"
        },
        "id": "345475D42A53D948A6D60181759683E8",
        "returnLeg": true,
        "startDate": "2018-07-18",
        "startLocation": {
          "countryCode": "DE",
          "city": "Berlin",
          "iataCode": "BER",
          "name": "Berlin(Alls)"
        },
        "startTime": "18:00"
      }
    ],
    "segmentType": {
      "category": "REQ_SEG_AIRFR",
      "code": "AIRFR"
    }
  }
}

HTTP Response

200 OK
{
  "href": "https://us.api.concursolutions.com/travelrequest/v4/expenses/B5FB8991E390474E875D6FD5BB1FDAF1",
  "id": "B5FB8991E390474E875D6FD5BB1FDAF1",
  "allocations": [
    {
      "allocationAmount": {
        "value": 432.45,
        "currency": "USD"
      },
      "approvedAmount": {
        "value": 432.45,
        "currency": "USD"
      },
      "allocationId": "79249903DC18464AAAD61062EA383BD4",
      "postedAmount": {
        "value": 432.45,
        "currency": "USD"
      },
      "expenseId": "B5FB8991E390474E875D6FD5BB1FDAF1",
      "percentEdited": false,
      "systemAllocation": true,
      "percentage": 100
    }
  ],
  "approvedAmount": {
    "value": 432.45,
    "currency": "USD"
  },
  "exchangeRate": {
    "value": 1,
    "operation": "MULTIPLY"
  },
  "expenseType": {
    "id": "AIRFR",
    "name": "Airfare"
   },
  "parentRequest": {
    "href": "https://us.api.concursolutions.com/travelrequest/v4/request/224AF3CDCC2A5244A37C72FA5770C6F2",
    "id": "224AF3CDCC2A5244A37C72FA5770C6F2",
    "template": "http://us.api.concursolutions.com/travelrequest/v4/request/{requestUuid}"
  },
  "postedAmount": {
    "value": 432.45,
    "currency": "USD"
  },
  "remainingAmount": {
    "value": 432.45,
    "currency": "USD"
  },
  "transactionAmount": {
    "value": 432.45,
    "currency": "USD"
  },
  "transactionDate": "2018-07-16T00:00:00.000Z",
  "tripData": {
    "agencyBooked": true,
    "selfBooked": false,
    "tripType": "ROUND_TRIP",
    "legs": [
      {
        "class": {
          "code": "1ST",
          "value": "05F71FA4ED235D479C6C7039F397DA79"
        },
        "endLocation": {
          "id": "4A33695120254EEC9261B24993DD413B",
          "countryCode": "DE",
          "countrySubDivisionCode": "DE-BE",
          "city": "Berlin",
          "iataCode": "BER",
          "name": "Berlin(Alls)"
        },
        "id": "B0F356643B38BC419AFE60E050BB79A4",
        "returnLeg": false,
        "startDate": "2018-07-16",
        "startLocation": {
          "id": "A168CDBA58AE42868961BC00278A91B3",
          "countryCode": "FR",
          "countrySubDivisionCode": "FR-75",
          "city": "Paris",
          "iataCode": "CDG",
          "name": "Charles De Gaulle Intl"
        },
        "startTime": "07:00"
      },
      {
        "endLocation": {
          "id": "A168CDBA58AE42868961BC00278A91B3",
          "countryCode": "FR",
          "countrySubDivisionCode": "FR-75",
          "city": "Paris",
          "iataCode": "CDG",
          "name": "Charles De Gaulle Intl"
        },
        "id": "345475D42A53D948A6D60181759683E8",
        "returnLeg": true,
        "startDate": "2018-07-18",
        "startLocation": {
          "id": "4A33695120254EEC9261B24993DD413B",
          "countryCode": "DE",
          "countrySubDivisionCode": "DE-BE",
          "city": "Berlin",
          "iataCode": "BER",
          "name": "Berlin(Alls)"
        },
        "startTime": "18:00"
      }
    ],
    "segmentType": {
      "category": "REQ_SEG_AIRFR",
      "code": "AIRFR"
    }
  }
}

Delete an expected expense from the Request

Scopes

travelrequest.write - Refer to Scope Usage for full details.

HTTP Request

URI Template

DELETE {datacenter}/travelrequest/v4/expenses/{expenseUuid}

Parameters

Name Type Format Description
expenseUuid string - Required The unique identifier of the expected expense to delete.
userId string - The unique identifier of the user performing the deletion of the expected expense. Required when connecting with a Company token. If empty, a 400 missingRequiredParam error code will be displayed.

Payload

None.

HTTP Response

v4 Expected Expense - HTTP Status Codes

To learn more about response HTTP status codes for this API see Travel Request v4 - HTTP Status Codes.

Payload

None.

Example

HTTP Request

DELETE https://us.api.concursolutions.com/travelrequest/v4/expenses/D65BDBD5D980F6498D67A92B06A457B0
Accept: application/json
Authorization: Bearer {token}

HTTP Response

200 OK
true

Get the list of comments for an existing expected expense

Scopes

travelrequest.write - Refer to Scope Usage for full details.

HTTP Request

URI Template

GET {datacenter}/travelrequest/v4/expenses/{expenseUuid}/comments

Parameters

Name Type Format Description
expenseUuid string - Required The unique identifier of the expected expense.
userId string - The unique identifier of the user getting the content of the comments. Required when connecting with a Company token. If empty, a 400 missingRequiredParam error code will be displayed.

Payload

None.

HTTP Response

v4 Expected Expense - HTTP Status Codes

To learn more about response HTTP status codes for this API see Travel Request v4 - HTTP Status Codes.

Payload

Comments

Example

HTTP Request

GET https://us.api.concursolutions.com/travelrequest/v4/expenses/B5FB8991E390474E875D6FD5BB1FDAF1/comments
Accept: application/json
Authorization: Bearer {token}

HTTP Response

200 OK
[
  {
    "author": {
      "firstName": "Steve",
      "lastName": "Smith"
    },
    "creationDateTime": "2019-07-12T11:51:14.000Z",
    "isLatest": true,
    "value": "I have reviewed the required amount, too expensive. You are allowed to a maximum of 100 USD for a business meal"
  },
  {
    "author": {
      "firstName": "John",
      "lastName": "Doe"
    },
    "creationDateTime": "2019-07-12T11:11:39.000Z",
    "isLatest": false,
    "value": "Please review the required amount for approval"
  }
]

Request v4 - Request Cash Advance Resources

Request Cash Advance Resources

Note: This cash advance detail endpoint is provided within the Concur Request API for feature parity purpose only. It is highly recommended to rely only on the list of cash advances link available in the Request payload response, and not on this cash advance detail URI presented below, which will be deprecated in the future.

Get the content of an existing cash advance

Scopes

travelrequest.write - Refer to Scope Usage for full details.

HTTP Request

URI Template

GET {datacenter}/travelrequest/v4/cashadvances/{cashAdvanceUuid}

Parameters

Name Type Format Description
cashAdvanceUuid string - Required The unique identifier of the cash advance.

Payload

None.

HTTP Response

v4 Cash Advance - HTTP Status Codes

To learn more about response HTTP status codes for this API see Travel Request v4 - HTTP Status Codes.

Payload

Cash Advance

Example

HTTP Request

GET https://us.api.concursolutions.com/travelrequest/v4/cashadvances/{cashAdvanceUuid}
Accept: application/json
Authorization: Bearer {token}

HTTP Response

200 OK
[
{
  "amountRequested": {
    "value": 1.000000,
    "currency": "USD"
  },
  "approvalStatus": {
    "code": "C_PEND",
    "name": "Pending Approval"
  },
  "cashAdvanceId: EF3E237ACAA3C449B808BA75BDD049FA,
  "exchangeRate": {
    "value": 1.00000000000000,
    "operation": "MULTIPLY"
  },
  "requestDate": 2019-11-14:T10:39:00.000Z"
}
]

Request v4 - Request Policy Resources

Request Policy Resources

Get the list of existing Request policies for a given user

Scopes

travelrequest.write - Refer to Scope Usage for full details.

HTTP Request

URI Template

GET {datacenter}/travelrequest/v4/userpolicies

Parameters

Name Type Format Description
userId string - The unique identifier of the user for whom the list of Request policies will be retrieved. Required when connecting with a Company token. If empty, a 400 missingRequiredParam error.

Payload

None.

HTTP Response

v4 Endpoinrts Policy - HTTP Status Codes

To learn more about response HTTP status codes for this API see Travel Request v4 - HTTP Status Codes.

Payload

List of Request Policies

Example

HTTP Request

GET https://us.api.concursolutions.com/travelrequest/v4/userpolicies
Accept: application/json
Authorization: Bearer {token}

HTTP Response

200 OK
[
  {
    "href": "https://us.api.concursolutions.com/travelrequest/v4/userpolicies/F4C8BD31CA9D4D6292795BE687EB9B2A",
    "id": "F4C8BD31CA9D4D6292795BE687EB9B2A",
   "name": "Internal training Request policy"
  },
  {
    "href": "https://us.api.concursolutions.com/travelrequest/v4/userpolicies/F10E6059B5A14A4C80327FE387491026",
    "id": "F10E6059B5A14A4C80327FE387491026",
   "name": "Client meeting Request policy"
  }
]

Request v4 - Travel Agency Resources

Travel Agency Resources

Manage the configuration for Travel Agencies integrated with Concur Request.

Get the description of a Travel Agency

Scopes

travelrequest.write - Refer to Scope Usage for full details.

HTTP Request

URI Template

GET {datacenter}/travelrequest/v4/travelagencies/{agencyUuid}

Parameters

Name Type Format Description
agencyUuid string - Required The unique identifier of the Travel Agency.

Payload

None

HTTP Response

v4 Travel Agency - HTTP Status Codes

To learn more about response HTTP status codes for this API see Travel Request v4 - HTTP Status Codes.

Payload

Travel Agency

Example

HTTP Request

GET https://us.api.concursolutions.com/travelrequest/v4/travelagencies/86B720AF168F1C4CA52E37AC710E897B
Accept: application/json
Authorization: Bearer {token}

HTTP Response

200 OK
{
  "href": "https://us.api.concursolutions.com/travelrequest/v4/travelagencies/86B720AF168F1C4CA52E37AC710E897B",
  "id": "2EC038D7C3CBBE4ABA0914425064D34F",
  "emailAddress": "agency-email@agencyname.com",
  "name": "myCompanyAgency"
}

Request v4 - Endpoints - Schemas

Schema

Request

Name Type Format Description
approvalLimitDate timestamp [RFC 3339] yyyy-MM-dd'T'HH:mm:ss.SSS'Z' The date by which the Request must be approved. This element appears only when integrated with Concur Travel.
approvalStatus object Approval Status The approval status of the Request.
approved boolean - Indicates whether this Request is approved.
approver object Employee The approver to whom the Request was sent.
authorizedDate timestamp [RFC 3339] yyyy-MM-dd'T'HH:mm:ss.SSS'Z' For approved Request, the date at which the approval process was completed.
businessPurpose string - The business purpose of the Request.
canceledPostApproval boolean - Indicates whether this Request was canceledPostApproval.
cashAdvances object ResourceLink The list of cash advances for this Request.
closed boolean - Indicates whether this Request is closed.
comment string - The last comment attached to this Request.
comments object ResourceLink The list of comments for this Request.
creationDate timestamp [RFC 3339] yyyy-MM-dd'T'HH:mm:ss.SSS'Z' The date the Request was created.
custom1 to custom20 object CustomField The details from the Custom fields. These fields may not have data, depending on the configuration.
endDate date [ISO 8601] yyyy-MM-dd The end date of the Request.
endTime time [ISO 8601] yyyy-MM-dd The end time of the Request.
everSentBack boolean - Indicates whether the Request has ever been sent back to the employee.
exceptions object ResourceLink The list of exceptions that have been raised to this Request.
expenses array ResourceLink Expected expenses attached to this Request.
extensionOf object RequestLink The Request that this Request is an extension of, or addendum to.
highestExceptionLevel string - The highest level of exception contained in this Request. Supported values: WARNING, ERROR, and NONE
href string [RFC 3986] Hyperlink to the resource for this Request.
id string - The unique identifier of the Request.
lastModified timestamp [RFC 3339] yyyy-MM-dd'T'HH:mm:ss.SSS'Z' The date the Request was last modified.
mainDestination object Location The main destination of the Request.
name string - The name of the Request.
owner object Employee The employee who owns the Request.
pendingApproval boolean - Indicates whether this Request is pending approval.
policy object ResourceLink The policy that applies to the Request.
requestId string 4 to 6 alphanumeric characters The public key of the Request (unique per customer).
startDate date [ISO 8601] yyyy-MM-dd The start date of the Request.
startTime time [ISO 8601] yyyy-MM-dd The start time of the Request.
submitDate timestamp [RFC 3339] yyyy-MM-dd'T'HH:mm:ss.SSS'Z' The date the Request was submitted (last submit date in case of recall).
totalApprovedAmount object Amount The total amount of approved expected expenses in the Request, expressed in the reimbursement currency of the employee at the time they created the Request.
totalPostedAmount object Amount The total amount of the Request, expressed in the reimbursement currency of the employee at the time they created the Request.
totalRemainingAmount object Amount The total amount not included in an Expense report, expressed in the reimbursement currency of the employee at the time they created the Request.
travelAgency object ResourceLink The travel agency office that is managing the trip associated to this Request.
operations array Link Links to operations available for the Request, depends on the current workflow status.
type object RequestType The type of the Request, inherited from the Request Policy Type.

Amount

Name Type Format Description
value number - Required The amount in the defined currency.
currency string [ISO 4217:2015] Required The 3-letter ISO 4217 code for the currency in which the amount is expressed.

Approval Status

Name Type Format Description
code string - The code for the approval status of the Request. Supported values: NOT_SUBMITTED, SUBMITTED, APPROVED, CANCELED, or SENTBACK
name string - The approval status of the Request in the current user's language.

Cash Advance

Name Type Format Description
amountRequested object Amount The amount of the cash advance in the Request, expressed in the reimbursement currency of the employee at the time they created the cash advance.
approvalStatus object Cash Advance Approval Status The approval status of the cash advance.
cashAdvanceId string - The unique identifier of the cash advance.
comment string - The last comment related to this cash advance.
exchangeRate object Exchange Rate The exchange rate that applies to the cash advance.
issueDate timestamp [RFC 3339] yyyy-MM-dd'T'HH:mm:ss.SSS The date the cash advance was issued.
requestDate timestamp [RFC 3339] yyyy-MM-dd'T'HH:mm:ss.SSS The date the cash advance was submitted (last submit date in case of recall).

Cash Advance Approval Status

Name Type Format Description
code string - The code for the approval status of the cash advance. Supported values: C_PEND, C_APPR, C_COMP, C_FILE, C_ISSU, C_NISU, C_NOTF, C_PECA, or C_REJE
name string - The approval status of the cash advance in the current user's language.

Comments

Name Type Format Description
author object Employee The employee who has created the comment in the expected expense.
creationDate timestamp [RFC 3339] yyyy-MM-dd'T'HH:mm:ss.SSS Creation date of the comment.
isLatest boolean - If true, the comment has been edited since the last workflow transition.
value string - The value of the comment.

CustomField

Name Type Format Description
code string - The short code for the list item. For non-list fields, this value will be blank.
value string - The value of the non-list item. For list fields, this is the unique id of the list item.
href string - The link to get this list item on the list service. Empty for non-list items.

Retrieving the listItemId requires to call the List API, which is currently being worked on for externalisation. In the meantime, to fill in a custom list item for the creation of a Request or an Expected Expense, clients may use one of the following workaround: * Use the copy down configuration feature to update custom fields from the Employee profile to the Request header, and from the Request header to the Expected expense. * For a limited number of list items that are part of a custom field, a Request containing those values in the related custom fields may be manually created. The list item unique id will then be retrieved by calling the get detail of this Request. The same process is used for all list items values of the list.

Employee

Name Type Format Description
firstName string - The first name of the employee.
href string [RFC 3986] Hyperlink to the resource.
id string [RFC 4122] Unique identifier of the related object.
lastName string - The last name of the employee.
middleInitial string - The middle initial of the employee.
template string - Hyperlink template to the resource.

Exceptions

Name Type Format Description
code string - The system exception code defined for the exception. Example: BADCODE
isBlocking boolean - Defines whether the exception will prevent the Request from being submitted.
level integer - The numeric level associated with the exception. Example: 99
message string - The user facing message defined for the exception.
source array Exception source The source that has raised the exception.
parameters map missingFields: array of missing field labels
missingFieldsIds: array of missing field ids
For missing fields exceptions, additional values giving more label and ids of the missing fields. Example : parameters : { "missingFields" : ["Request Name", "Purpose"], "missingFieldsIds" : [ "Name", "Purpose" ] }

Exception Source

Name Type Format Description
href string [RFC 3986] Hyperlink to the resource.
id string [RFC 4122] Unique identifier of the source.
type string - Defines the type of the source. Supported values: ALLOCATION, CASH_ADVANCE, EXPENSE, and HEADER
Name Type Format Description
rel string [RFC 5988] Relation type as defined by the server. There are registered relation types listed in RFC 5988 6.2.2. Initial Registry Contents including pagination relation types of next, prev, first and last.
href string [RFC 3986] Hyperlink to the resource.

List of Request

Name Type Format Description
data array Request List of Requests in the page requested.
operations array Link Links to next, prev, first and last pages.

List of Request Policies

Name Type Format Description
- array Request Policy List of active Requests policies for a given user.

Location

Name Type Format Description
city string - Required for all city location type (not airport, or rail station) The city name of the location.
countryCode string [ISO 3166-1] Required if city or name is used The ISO 3166-1 country code.
countrySubDivisionCode string [ISO 3166-2] The ISO 3166-2 country sub code.
iataCode string - The IATA code of an airport location.
id string - The id of the location.
latitude number - The latitude of the location.
locationCode string - Required if rail is used The code of the location.
locationType string - Required if rail is used The type of the location.
longitude number - The longitude of the location.
name string - Required for rail station The name of the location. Always provide the countryCode value in addition to the name.

Below are the different node expected in the POST endpoints by location type (City, Rail station, or Airport) - example for endLocation field:

Airport json "endLocation": { "city": "Moscow", "name": "Sheremetyevo", "countryCode": "RU", "iataCode": "SOV" }

City json "endLocation": { "city": "Vienna", "countryCode": "AT" }

Rail station (locationCode exists, locationType depends of rail provider) json "endLocation": { "name": "MARSEILLE ST CHARLES", "countryCode": "FR", "locationCode": "FRMSC", "locationType": "RAIL_2C" } Location types for Rail :

Location Type Railway company
RAIL_0Z Swiss Federal Railways
RAIL_2A Deutsche Bahn AG
RAIL_2C SNCF
RAIL_2H Thalys International
RAIL_2R VIA Rail Canada Inc.
RAIL_2V Amtrak
RAIL_9F Eurostar International Limited
RAIL_XH China Railway
RAIL_Z0 UK Rail
STD Standard rail locations
Name Type Format Description
href string [RFC 3986] Hyperlink to the resource.
id string [RFC 4122] Unique identifier of the related object.
template string - Hyperlink template to the resource.
Name Type Format Description
requestId string 4 to 6 alphanumeric characters The public key of the Request (unique per customer).

Request Policy

Name Type Format Description
href string [RFC 3986] Hyperlink to the resource for this Request policy.
id string - The Request policy unique identifier.
name string - The name of the Request policy.

Request Type

Name Type Format Description
code string - The code of the type inherited from the Request Policy type.
label string - The label of the type inherited from the Request Policy Type.

Expected Expense

Name Type Format Description
allocations object Allocation The details of the allocations for this expected expense.
approvedAmount object Amount The approved amount of the expected expense entry, in the transaction currency of the Request.
budgetAccrualDate timestamp [RFC 3339] yyyy-MM-dd'T'HH:mm:ss.SSS'Z' The date to determine which budgets are affected.
businessPurpose string - The business purpose of the Request entry.
comments object ResourceLink The list of comments for this expected expense.
custom1 to custom40 object CustomField The details from the Custom fields. These fields may not have data, depending on the configuration.
exchangeRate object Exchange Rate The exchange rate that applies to the entry.
expenseType object Expense Type The expense type of the entry. Required for expected expenses, automatically set for segments depending on the SegmentType code.
href string [RFC 3986] Hyperlink to the resource for this Request entry.
id string - The unique identifier of the expected expense entry.
lastComment string - The last comment (most recent) of the expected expense entry.
lastModifiedDate timestamp [RFC 3339] The date when this expected expense was last modified.
location object Location The location of the expected expense entry.
orgUnit1 to orgUnit6 object Amount The details from the Custom fields. These fields may not have data, depending on the configuration.
postedAmount object Amount The posted amount of the expected expense entry, in the transaction currency of the Request.
parentRequest object ResourceLink The parent Request of the expected expense.
remainingAmount object Amount The remaining amount of the expected expense entry, in the transaction currency of the Request.
source enum - The source that created the expected expense. Supported values: CASH_ADVANCE or TRAVEL_ALLOWANCE. This field will be empty in any other case
transactionAmount object Amount Required The amount of the expected expense entry, in the transaction currency paid to the vendor.
transactionDate timestamp [RFC 3339] yyyy-MM-dd'T'HH:mm:ss.SSS'Z' Required The date of the transaction.
travelAllowance object Travel Allowance The Travel allowance.
tripData object Trip Data The description of the trip.
vendor object Vendor The vendor of the expected expense entry.

Allocation

Name Type Format Description
allocationAmount object Amount The amount of the allocation calculated with the percentage value multiplied by the transaction amount on the expected expense. This amount is given in the transaction's currency and rounded to eight digits after the decimal point.
approvedAmount object Amount The amount of the allocation calculated with the percentage value multiplied by the approved amount on the expected expense. This amount is given in the user's currency and rounded to eight digits after the decimal point.
allocationId string - The unique allocation identifier.
custom1 to custom20 object CustomField The details from the Custom fields. These fields may not have data, depending on the configuration.
expenseId string - The unique identifier of the expected expense associated with the allocation.
percentEdited boolean - Whether the allocation percent has been edited.
percentage number - The percentage of the total expected expense that this allocation represents.
postedAmount object Amount The amount of the allocation calculated with the percentage value multiplied by the posted amount on the expected expense. This amount is given in the user's currency and rounded to eight digits after the decimal point.
systemAllocation boolean - Whether the allocation is a system allocation, usually hidden from the user. If displayed to the user, should be read-only.

Exchange Rate

Name Type Format Description
operation string - Exchange rate operation. Supported values: MULTIPLY, DIVIDE
value number - Exchange rate value.

Expense Type

Name Type Format Description
id string - Required Unique identifier of the expense type.
name string - Name of the expense type.

List Item Field

Name Type Format Description
code string - The short code of the list item.
value string - Unique identifier of the list item.
href string [RFC 3986] Hyperlink to the resource for the list item.

Segment Leg

Name Type Format Description
class list List Item Field The booking class of the segment leg.
classOfService string - The class of service of the segment leg. For example, in the case of an air segment, this field would contain the one-letter booking code: Y for economy class, or F for first class.
comment string - Contains the last comment saved in this segment leg.
custom1 to custom40 object CustomField The details from the Custom fields. These fields may not have data, depending on the configuration.
endDate date [ISO 8601] YYYY-MM-DD The date of the end of this segment leg. It represents the arrival date of AIRFR and TRAIN segments, check out date for HOTEL, or drop off for CARRT.
endLocation object ResourceLink The location where this segment leg arrives. For example, the arrival location for an air segment.
endLocationDetail string - Details about the end location. This would contain details about the name of a hotel, or some details about a car rental agency for example.
endTime time [ISO 8601] HH:MM The time for the end of this segment leg.
id string - The unique identifier of the segment leg.
returnLeg boolean - Indicates whether this leg is the return leg of a round trip. In case of a ROUND_TRIP, if not explicitly set, the second segment leg will be considered as the return leg.
startDate date [ISO 8601] YYYY-MM-DD The date of the beginning of this segment leg.
startLocation object ResourceLink The start location of this segment leg. This would be the departure location for an air segment for example.
startLocationDetail string - Details about the start location. This would contain details about the name of a hotel, or some details about a car rental agency for example.
startTime time [ISO 8601] HH:MM The time for the beginning of this segment leg.
segmentLocator string - This is the identifier for Concur Travel segments (if applicable).
vendorName string - Contains the vendor description of the segment leg.

Segment Type

Name Type Format Description
category enum - Describes the category of this segment type. Supported values: REQ_SEG_AIRFR, REQ_SEG_CARRT, REQ_SEG_HOTEL, REQ_SEG_LIMOF, REQ_SEG_RAILF, REQ_SEG_TAXIF, REQ_SEG_MISC, REQ_SEG_PARKG, REQ_SEG_DININ, REQ_SEG_EVENT
code string - Required The code of the segment type. Supported values: AIRFR, CARRT, HOTEL, LIMOF, RAILF, TAXIF, MISC, PARKG, DININ, EVENT or custom codes

It can be REQ_SEG_AIRFR / AIRFR for a regular air segment, or REQ_SEG_AIRFR / 10325 for a custom air segment.

Example:

{
  "category": "REQ_SEG_AIRFR",
  "code": "AIRFR"
}

Travel Agency

Name Type Format Description
emailAddress string - The travel agency email address.
id string - The travel agency unique identifier.
name string - The travel agency office name.
proposalType string - The travel agency proposal type. Supported values: CWTF, AEBT, API

Travel Allowance

Name Type Format Description
dailyTravelAllowanceId string - The fixed daily travel allowance id associated with the expected expense.

Trip Data

Name Type Format Description
agencyBooked boolean - If true, this travel is (or has to be) handled by a travel agency.
legs list Segment Leg The list of the legs of the travel.
tripType string - Indicates the type of this trip. Supported values: ONE_WAY, ROUND_TRIP, or MULTI_STOPS. If not provided, will be detected from the given legs.
segmentType object Segment Type Required The type of the segment.
selfBooked boolean - If true, this travel has been reserved by Concur Travel, or if Concur Travel has retrieved the trip information in the GDS.

Vendor

Name Type Format Description
id string - The vendor identifier of the entry.
name string - The vendor description of the entry.

Request v4 - HTTP Status Codes

HTTP Status Codes

HTTP Status Code Response Body Description
200 OK - Your GET request succeeded.
201 Created - Your POST request succeeded.
400 Bad Request badParam the request has bad parameter(s) {requestName} The name of the request doesn't have the expected format
- invalidJson invalid json structure An input JSON structure couldn't be parsed
- invalidDate error while parsing date value {dateValue} A date or datetime value couldn't be parsed
- invalidUuid for concur-correlationid {correlationId} The concur correlation id of the request is not a valid UUID
- invalidUuid {requestName} The name of the request doesn't have the expected format
- invalidLocation the location cannot be resolved, please provide either {iataCode} or {countryCode} and {cityName} Required location input is missing
- invalidLocation the location cannot be resolved, no location found for iataCode={iataCode} No location found matching the iataCode provided
- invalidLocation the location cannot be resolved, no city found for countryCode={countryCode} and cityName={cityName} No location found matching the country code and city name provided
- invalidLocation the location cannot be resolved, multiple locations available for countryCode={countryCode} and cityName={cityName} Multiple locations found matching the country code and city name provided
- invalidPolicy invalid policy id
- listValidationError validation of list items failed
- missingRequiredField at least 1 required field has an empty value A request with no value on a mandatory field has been submitted
- blockingException at least 1 blocking exception A request with a blocking exception has been submitted
- multiLegNotAllowed cannot save a multi leg, multi-leg is not enabled for this entity The multi leg support is not allowed for the entity
- reportTemplateNotFound failed to retrieve report template The multi leg support is not allowed for the entity
- unsupportedParam the request has unsupported parameter(s) Some parameter(s) of the request are not supported
- missingRequiredParam the request is missing required parameter(s) The request is missing some required parameter(s)
- companyNotFound the company for this request has not been found The company for this request has not been found
- userNotFound user {id} not found The user Id for this request has not been found
- invalidUuid invalid {Uuid} for the userId The unique identifier for this userId is not valid
- - Limit must be less than or equal to 100 limit must be less than or equal to 100
- - Limit must be greater than or equal to 1 limit must be greater than or equal to 1
- - Limit must contains only digits Limit must contains only digits
401 Unauthorized invalidUser the request's user is invalid invalid or non existent authorization HTTP header
403 Forbidden permissionDenied permission denied User approving their own Request, or without approver/processor role
- requestStatusNotApproved the Request is not approved or canceled after approval
- userIsNotAllowed user is not allowed to access this resource
- requestStartDateInTheFuture expense report cannot be create from an approved Request before Request start
- publicApiNotAllowed entity is not allowed to access this resource
- publicApiNotAllowed this resource is not public
- CASH_ADVANCE_CANNOT_SUBMIT_AS_DELEGATE The cash advance cannot be submitted by the delegate.
- CASH_ADVANCE_CANNOT_APPROVE_OWN_CA You cannot approve your own cash advance.
404 Not Found notFound resource not found You tried to get a non-existing request
408 Request Timeout timeOut timeout has occurred
409 Conflict NO_APPROVER No approver was found. You must identify an approver before the request moves on to the next workflow step.
- NO_APPROVER_NOT_EDITABLE_STEP There are no approvers defined in your workflow. Contact your Expense administrator for assistance.
- NO_APPROVER_CHANGE_MY_INFO Missing the required approver for next workflow step. You may be able to select an approver; otherwise contact your Administrator for assistance.
- NO_AUTH_APPROVERS This request cannot be sent to the next approver. This workflow step must be approved by a specialised approver called an Authorised Approver. There are no Authorised Approvers defined. Please contact your Request administrator for assistance.
- REVIEW_APPROVAL_FLOW_APPROVER Review approvers in the workflow.
- APPROVER_CUM_REPORTOWNER You cannot send this request to this approver since this person created this request.
- APPROVER_CUM_REPORTOWNER_EDITABLE Your workflow is configured such that the request would come back to the request owner during some step. Please contact your Employee Administrator to change the approvers.
- INVALID_AUTH_APPROVER This request cannot proceed without an approver type of Authorised Approver. Select an approver who is an Authorised Approver before proceeding.
- CONFIG_INVALID_NEXT_STEP You must identify an approver before the request moves on to the next workflow step.
- STEP_EXIT_BLOCKING_BY_EXCEPTION One or more blocking exceptions are preventing approval submission. Resolve the exception before proceeding.
- CASH_ADVANCE_SUBMIT_GENERIC Cash Advance Status Change: Failure
- CASH_ADVANCE_SUBMIT_ALREADY_SUBMITTED The cash advance has already been submitted and cannot be submitted again.
- CASH_ADVANCE_CONFIG_INVALID_NEXT_STEP Cash Advance: You must identify an approver before the request moves on to the next workflow step
- CASH_ADVANCE_APPROVER_CUM_REPORTOWNER Cash Advance: You cannot send this request to this approver since this person created this request.
- CASH_ADVANCE_APPROVER_CUM_REPORTOWNER_IS_EDITABLE_BY Cash Advance: Your workflow is configured such that the claim would come back to the claim owner during some step. Please contact your Employee Administrator to change the approvers.
- CASH_ADVANCE_INVALID_AUTH_APPROVER Cash Advance: This request cannot be sent to the next approver. This workflow step must be approved by a specialised approver called an Authorised Approver. The selected approver is not an Authorised Approver. Select another approver.
- CASH_ADVANCE_NO_APPROVER Cash Advance: You must identify an approver before the request moves on to the next workflow step.
- CASH_ADVANCE_NO_APPROVER_CHANGE_MY_INFO Cash Advance: Missing the required approver for the next workflow step. Contact your Expense administrator for assistance.
- CASH_ADVANCE_NOT_AN_APPROVER Cash Advance: This request cannot be sent to the next approver because the selected approver is no longer authorised to approve requests. Please select another approver.
- CASH_ADVANCE_REVIEW_APPROVAL_FLOW_APPROVER Cash Advance: Review Approvers in the workflow.
500 Internal Server Error timeOut timeout has occurred
- createReportError error while creating an expense report
- internalServerError internal server error
- associateReportError error while associating an expense report to a Request
503 Service Unavailable circuitBreaker Circuit Breaker is open, please try again on a different node The server node might be unavailable, be retrying the request you may reach a healthy node
- entityOffline Entity is offline, please try again later.
- CLIQBOOK_APPROVAL_FAILURE This request cannot be approved due to trip approval failure.
- CLIQBOOK_APPROVAL_RETRY This request cannot be approved immediately. Please try again later.
- CLIQBOOK_CANCEL_FAILURE This request cannot be cancelled due to trip cancel failure.

Travel Profile

Travel Profile v2

The Travel Profile service consists of a set of resources that provide travel profile functionality customized in specific ways for developers, travel suppliers, and travel management companies (TMCs).

Profile v2

These web services can be used to retrieve travel profile information for a specified user, or a list of travel profile summaries.

Available to Developers, travel suppliers, and TMCs.

Loyalty Program v1

This web service can be used to update loyalty information for the user as entered in Concur.

Available to Travel suppliers and TMCs.

Company Notification v1

A subscription to a notification when any user in the Concur company changes the specified features of their Concur account or data. Currently supports notifications for the following events: Itinerary change (create or update), Travel Profile basic information change. To obtain notifications, the Concur users must grant access to their travel profile using the Web authorization flow.

Available to Travel suppliers.

User Notification v1

A subscription to a notification when the Concur user changes the specified features of their Concur account or data. Currently supports notifications for the following events: Itinerary change (create or update), or Travel Profile basic information change. This functionality is restricted to Travel Suppliers or TMCs (Travel Management Companies) who have registered with Concur. To obtain notifications, the Concur users must grant access to their travel profile using the Web authorization flow.

Available to Travel suppliers.

Configuration

Travel supplier or TMC partner applications must complete the Concur application review process before they can access production user data. Suppliers can only update Loyalty Program information for the programs that they manage. TMCs can access all the user's Travel Profile data, regardless of vendor.

Travel Profile v2 - Resource

The Travel Profile resource represents a Concur Travel profile that contains travel-related information about a user.

Operations

Detailed descriptions of requests and responses are available in the documentation for each HTTP method.

Get a Travel Profile

This endpoint provides travel profile information for the specified user. The travel profile includes information such as the user's identity, contact information, rate preferences and discount codes, preferences by travel type, and custom fields.

URI

https://{InstanceURL}/api/travelprofile/v2.0/profile

Request parameters

All request parameters are optional. To identify a specific user by Login ID or XML Sync ID, you can specify the following request parameters:

Parameter Name Parameter Type Data Type Description
userid_type Path string The type of user identification to use. Possible values are: login and xmlsyncid
userid_value Path string The user's Login ID or XML Sync ID, depending on which user type is selected. This parameter must be provided in conjunction with the userid_type parameter.

Headers

Content-Type header

application/xml

Authorization header

Authorization: OAuth {access_token}

Where access_token is the OAuth 2.0 access token of the user whose travel profile information you want to retrieve.

Create / Update Travel Profile

Creating/Updating a Profile uses the same model as what is retrieved.

Helpful Tips

  • Minimum elements required to create a new user include:
    • FirstName
    • LastName
    • TravelConfigID (used to verify agency and Company access to create user)
    • LoginID
    • Password
    • RuleClass (uses default rule class if not provided)
  • Omitted elements will be ignored and not updated
  • Empty elements of datatype string will be cleared out; nillable elements will be cleared out if set as nil refer to XSD for nillable elements.

Headers

Content-Type header

application/xml

Authorization header

Authorization: OAuth {access_token}

Where access_token is the OAuth 2.0 access token of the user whose travel profile information you want to retrieve or update.

Schema

The complete schema definition is available here: Travel Profile XSD.

SAP Concur reserves the right to change the XSD. Reading/writing strictly to the XSD will result in breakage as new XML elements are added.

The Profile root element contains:

Travel Profile v2 - General

Name Data Type Description Update Create Comments
NamePrefix string The user's name prefix. Format: nvarchar(60) - - -
FirstName string The user's first name. Format: nvarchar(60) - Required -
MiddleName string The user's middle name. Format: nvarchar(60) - - -
LastName string The user's last name. Format: nvarchar(60) - Required -
NameSuffix string The user's name suffix. Format: nvarchar(60) - - -
PreferredName string The user's preferred name. Format: nvarchar(60) - - -
JobTitle string The user's job title. Format: nvarchar(255) - - -
CostCenter string The user’s cost center. Format: nvarchar(25) - - Requires Company Details scope.
CompanyEmployeeID string The user’s employee ID. Format: nvarchar(48) - - Requires Company Details scope. Must be unique in the company.
Division string The user's division. Format: nvarchar(60) - - Requires Company Details scope. Must already be setup in the company configuration.
PreferredLanguage string The user's preferred language locale. Example: United States English is en-US. Format: varchar(20) - - -
EReceiptOptIn boolean Whether the user has opted in to receive e-receipts. Format: true\false - -
HasOpenBooking boolean Whether the user has the TripLink User (formerly Open Booking User) permission. Format: true\false Cannot Update - -
CountryCode string The country code in from the ISO 3166-1 alpha-2 country code specification. Format: char(2) Cannot Update - -
CompanyName string The user's company name. Format: nvarchar(255) Cannot Update - -
CompanyID string The user's company ID. Format: varchar(255) Cannot Update - Requires Company Details scope.
RuleClass string The user's rule class. Format: nvarchar(60) - - Must already be setup in the company.
TravelConfigID string The user's TravelConfig. Format: varchar(255) - Required -
MedicalAlerts string The user's medical alerts. Format: nvarchar(255) - - Requires Medical Alerts Scope.
AgencyNumber string The TravelConfig’s Agency IATA Number. Format: varchar(255) Cannot Update - -
SearchID string The user's Search ID. Format: varchar(64) - - -
GDSProfileName string The user's GDS profile name. Format: varchar(60) - - Requires TMC Specific scope.
SabreProfileId string The user's Sabre Travel Profile Id. Format: varchar(60) - - Requires TMC Specific scope.
UUID string The user's Unique Identifier. Format: GUID, 32 characters Cannot Update - Requires TMC Specific scope.

NOTE: If MiddleName is provided, the NoMiddleName flag in TSAInfo section is set to false.

EmergencyContact

The emergency contact information provided.

Name Data Type Description Update Create Comments
Name string The emergency contact name Format: nvarchar(255) - - -
Relationship string The relationship to the user. Values are: Spouse, Brother, Parent, Sister, LifePartner, Other - - -
Phone list - - - If multiple values of the same telephone type are provided, only the last one will be saved. See below for the list elements.
Address Address Street Address. Format: nvarchar(max) - - -

Address

Name Data Type Description Update Create Comments
Street string Street Address. Format: nvarchar(max) - - -
City string The city name. Format: nvarchar(30) - - -
StateProvince string The state or province. Format: nvarchar(30) - - -
CountryCode string The country code in from the ISO 3166-1 alpha-2 country code specification. Format: char(2) - - -
PostalCode string The postal code. Format: nvarchar(20) - - -

Phone List

Name Data Type Description Update Create Comments
PhoneNumber string The emergency contact’s phone number. Format: nvarchar(60) - - No unicode characters.
Type string This contains a “type” attribute with values of DayTime or Alternate. Required Required -

Telephones

The Telephones parent element contains a Telephone child element for each included telephone. The Telephone element has the attributes shown in the Response Class section and contains the following child elements:

Name Data Type Description Update Create Comments
Type attribute string Type of phone. Values are: Home, Work, Fax, Pager, Other, and Cell required required -
ContactOptIn attribute boolean Whether the user has opted in to being contacted on this phone. Only appears when the phone type is Cell. Format: true\false - - -
PrimaryMobile attribute boolean This is the user's preferred mobile device. Format: true\false - - -
CountryCode string The country code in from the ISO 3166-1 alpha-2 country code specification. Format: Char(2) required (Cell) required (Cell) Required for Cell types.
PhoneNumber string The phone number as entered by the user, which may contain characters such as () or -. Format: nvarchar(60)
required (Cell) required (Cell) Required for Cell types.
Extension string The phone extension. Format: nvarchar(60) - - -
MobileDevice string The OS of the mobile device. Values are:
Android Phone
Android Tablet
Blackberry
iOS Phone
iOS Tablet
Not a smartphone
Other iOS device
Other smartphone
Unknown
Window Mobile
- - -
MobileName string The name the user assigned to the mobile device. Format: nvarchar(255) - - -

NOTES

Addresses

The Addresses parent element contains an address child element for each included address. The address element has the attributes shown in the response class section and contains the following child elements:

NOTE: The values returned for the Address child elements are as entered by the user. The fields do not enforce formatting and may have a wide variety of values.

Name Data Type Description Update Create Comments
Type attribute string Address type. Values are: Home or Work required required If multiple values are provided for either address type, the last one will be the one saved in the creation/update.
Street string Street Address. Format: nvarchar(max) - - -
City string The city name. Format: nvarchar(30) - - -
StateProvince string The state or province. Format: nvarchar(30) - - -
CountryCode string The country code in from the ISO 3166-1 alpha-2 country code specification. Format: char(2) - - -
PostalCode string The postal code. Format: nvarchar(20) - - -
Longitude string Longitude value of Work Address. Cannot Update - -
Latitude string Latitude value of Work Address. Cannot Update - -

NationalIDs

The NationalIDs parent element contains a NationalID child element for each included National ID. The NationalID element contains the following child elements:

Name Data Type Description Update Create Comments
NationalIDNumber string The user's national identification number. Format: nvarchar(100) - - No unicode accepted. Only saves one national ID value. If multiple are provided, W016 warning message is returned.
IssuingCountry string The country the national ID was issued in. Format: varchar(2) - - -
Expiration date The expiration date of the national ID. Format: YYYY-MM-DD - - Min - 01/01/1753, Max - 12/31/9999

NOTE: Only one National ID can be accepted.

DriversLicenses

The DriversLicenses parent element contains a DriversLicense child element for each included licenses.

Name Data Type Description Update Create Comments
DriversLicenseNumber string The user's driver license identification number. Format: nvarchar(100) - - Only saves one Drivers License Number value. If multiple are provided, W016 warning message is returned.
IssuingCountry string The country the license was issued in. Format: varchar(2) - - -
IssuingState string The state the license was issued in. Format: nvarchar(30) - - -
Expiration date The expiration date of the license. Format: YYYY-MM-DD - - Min - 01/01/1753, Max - 12/31/9999

NOTE: Only one Drivers License can be accepted.

HasNoPassport

A flag which is triggered automatically when adding a new passport to a user.

Name Data Type Description Update Create Comments
HasNoPassport boolean Format: true\false. - If passport value added, then this value becomes false.

Passports

A list of passports in the user's profile:

Name Data Type Description Update Create Comments
PassportNumber string The user's passport number. Format: nvarchar(100) Required Required -
PassportNationality string The user's passport nationality. Format: char(2) Required Required -
PassportExpiration date The date the user’s passport expires. Format: YYYY-MM-DD - - Min - 01/01/1900, Max - 06/06/2079
PassportDateIssued date The date the user’s passport was issued. Format: YYYY-MM-DD - - Min - 01/01/1900, Max - 06/06/2079
PassportCityIssued string The city the user’s passport was issued in. Format: nvarchar(60) - - -
PassportCountryIssued string The country code in from the ISO 3166-1 alpha-2 country code specification. Format: char(2) - - -

NOTE: there can only be 2 passports associated to a user. If more than two passports are provided, W016 warning message is returned.

Visas

A list of visas in the user's profile.

Name Data Type Description Update Create Comments
VisaNationality string The user's visa nationality. Format: char(2) Required Required -
VisaNumber string The user's visa nationality. Format: nvarchar(100) Required Required -
VisaType string The user's visa type. Values are Unknown, SingleEntry, DoubleEntry, MultiEntry, ESTA, ETA, and SchengenVisa. - - -
VisaDateIssued date The date the user’s visa was issued. Format: YYYY-MM-DD - - Min - 01/01/1900 Max - 06/06/2079
VisaExpiration date The date the user’s visa expires. Format: YYYY-MM-DD - - Min -01/01/1900 Max - 06/06/2079
VisaCityIssued string The city the user’s visa was issued in. Format: nvarchar(60) - - -
VisaCountryIssued string The country code in from the ISO 3166-1 alpha-2 country code specification. Format: char(2) - - -

NOTE: Visas will sync with existing visas. Any existing Visas not provided in the list will be deleted.

EmailAddresses

The EmailAddresses parent element contains an EmailAddress child element for each included email address. It contains the following child element:

Name Data Type Description Update Create Comments
EmailAddress string The user's email address. Format: Varchar(255) - - -
Contact attribute boolean The Contact attribute specifies whether the email address should be used for travel notifications. Format: true\false. - - -
Type attribute string The type of email address. Values are: Business, Personal, Supervisor, TravelArranger, Business2, Other1, and Other2. Required Required Supervisor and TravelArranger cannot be updated. Only 1 of each type is allowed. W016 Error is returned

RatePreferences

The RatePreferences parent element contains the following child element:

Name Data Type Description Update Create Comments
AAARate boolean Whether the user is eligible for the AAA rate. Format: true\false - - -
AARPRate boolean Whether the user is eligible for the AARP rate. Format: true\false - - -
GovtRate boolean Whether the user is eligible for the Government rate. Format: true\false - - -
MilitaryRate boolean Whether the user is eligible for the Military rate. Format: true\false - - -

DiscountCodes

The DiscountCodes parent element contains a DiscountCode child element for each included discount code.

Name Data Type Description Update Create Comments
DiscountCode string The discount code for the specified vendor. - - unable to update
Vendor attribute string Specifies the name of the vendor for the discount code. - - unable to update

NOTE: Discount code elements are not available to create or update.

Air

The Air parent element contains the user's air travel preferences and contains the following child elements:

Name Data Type Description Update Create Comments
AirMemberships - The AirMemberships element only appears if the request came from a travel supplier for this travel type, or from a TMC. This element contains AirMembership child elements. - - -
Seat - This element contains air seat child elements. - - -
Meals string This parent element contains the MealCode child element that indicates the meal preference of the traveler. See Reference for possible values. - - Defaults to Regular Meal
HomeAirport string The user's home airport. varchar(3) - - Must be an existing IATA code.
AirOther string Other Air related description - - -

Air Memberships

Name Data Type Description Update Create Comments
VendorCode string The code for the vendor that manages the loyalty program. varchar(2) Required Required Must be a valid VendorCode for the membership type. This list can be made available upon request.
AccountNo string The user's account identifier in the loyalty program. varchar(60) Required Required -
Status string Name of the user's current level in the loyalty program. varchar (100) - - -
StatusBenefits string Description of a benefit of the loyalty program at the current status. - - -
PointTotal string The user's total number of points in the loyalty program. - - -
SegmentTotal string The user's total segments in the loyalty program. - - -
NextStatus string Name or description of next higher status level in the loyalty program. - - -
PointsUntilNextStatus string Loyalty points required to next status level. - - -
SegmentsUntilNextStatus string Booking segments to next status level. - - -
IsSenator boolean Lufthansa specific field. Format: true\false - - -

Seat

Name Data Type Description Update Create Comments
InterRowPositionCode string Preferred position in an airplane row. Format: Window, Aisle, Middle, DontCare. - - -
SectionPositionCode string Preference for position in plane. Format: Bulkhead, Forward, Rear, ExitRow, DontCare. - - -

Rail

The Rail parent element contains the user's rail travel preferences and contains the following child elements:

Name Data Type Description Update Create Comments
Seat string This element contains seat preferences. Format: Aisle, Window, DontCare - - -
Coach string This element contains coach preferences. Format: Compartment, Coach, CoachWithTable, DontCare - - -
NoiseComfort string This element contains noise comfort preferences. Format: QuietSpace, MobileSpace, DontCare - - -
Bed string This element contains bed preferences. Format: Lower, Upper, Middle, DontCare - - -
BedCategory string This element contains bed category preferences. Format: WomenOnly, MenOnly, DontCare - - -
Berth string This element contains berth preferences. Format: Lower, Upper, Middle, DontCare - - -
Deck string This element contains deck preferences. Format: Lower, Upper, DontCare - - -
SpaceType string This element contains space type preferences. Format: Panorama, SeatWithTable, Solo, Salon, Kiosk, InclineSeat, DuoSideBySide, DuoFaceToFace, Club6, Club4, Carre, DisabledCompanionSpace, DontCare - - -
FareSpaceComfort string This element contains fare space comfort preferences. Format: DedicatedBusiness, Business, IntermediateLeisure, Leisure, StandardLeisure, DontCare - - -
SpecialMeals string This element contains special meal preferences. Format: LowFat, LowSalt, GlutenFree, Diabetic, Muslim, Kosher, Vegetarian, VegetarianLactoOvo, DontCare - - -
Contingencies string This element contains contingencies preferences. Format: Bike, WomenOnly, WheelchairSpace, DontCare - - -
RailMemberships - This element contains RailMembership child elements - - -

Rail Membership

Name Data Type Description Update Create Comments
VendorCode string The code for the vendor that manages the loyalty program. varchar(2) Required Required Must be a Valid Vendor Code for the Membership Type. This list can be made available upon request.
AccountNo string The user's account identifier in the loyalty program. varchar(60) Required Required See Below.
Status string Name of the user's current level in the loyalty program. varchar (100) - - -
StatusBenefits string Description of a benefit of the loyalty program at the current status. - - -
PointTotal string The user's total number of points in the loyalty program. - - -
SegmentTotal string The user's total segments in the loyalty program. - - -
Expiration DateTime The user's expiration date in the loyalty program. Min - 01/01/1753, Max - 12/31/9999 - - -
NextStatus string Name or description of next higher status level in the loyalty program. - - -
PointsUntilNextStatus string Loyalty points required to next status level. - - -
SegmentsUntilNextStatus string Booking segments to next status level. - - -
BahnCardClass string Bahn card class. Valid values are First and Second. - - -
BahnCardType string Bahn card type. Valid values include NA (for non-rail programs), Card25, Card50, Card100, Business25, and Business50. - - -

Car

The Car parent element contains the user's car travel preferences. It contains the following child elements:

Name Data Type Description Update Create Comments
CarSmokingCode string Smoking car preferred. Format: DontCare, NonSmoking, Smoking - - -
CarGPS boolean Car GPS preference. Format: true\false. - - -
CarType string Car type preference. Values are:
DontCare
Mini
Economy
EconomyHybrid
Compact
CompactHybrid
Intermediate
IntermediateHybrid
Standard
StandardHybrid
FullSize
FullSizeHybrid
MiniVan
Luxury
Premium
StandardSUV
IntermediateSUV
FullSizeSUV
FullSizePickup
Specialized
- - -
CarMemberships - The CarMemberships element only appears if the request came from a travel supplier for this travel type, or from a TMC. This element contains CarMembership child elements for each included membership. - - -
CarOther string Other Car related description. Format: varchar(30) - - -
CarSkiRack boolean Car ski rack preference. Format: true\false. - -
CarTransmission string Car transmission type. Values are: DontCare, Automatic, Manual - - -

Car Memberships

Name Data Type Description Update Create Comments
VendorCode string The code for the vendor that manages the loyalty program. varchar(2) Required Required Must be a Valid Vendor Code for the Membership Type. This list can be made available upon request.
AccountNo string The user's account identifier in the loyalty program. varchar(60) Required Required See Below.
Status string Name of the user's current level in the loyalty program. varchar (100) - - -
StatusBenefits string Description of a benefit of the loyalty program at the current status. - - -
PointTotal string The user's total number of points in the loyalty program. - - -
SegmentTotal string The user's total segments in the loyalty program. - - -
Expiration DateTime The user's expiration date in the loyalty program. - - Min - 01/01/1753, Max - 12/31/9999
NextStatus string Name or description of next higher status level in the loyalty program. - - -
PointsUntilNextStatus string Loyalty points required to next status level. - - -
SegmentsUntilNextStatus string Booking segments to next status level. - - -

Hotel

The Hotel parent element contains the user's hotel travel preferences. It contains the following child elements:

Name Data Type Description Update Create Comments
SmokingCode string Smoking room preference. Values: DontCare, NonSmoking,Smoking - - -
HotelMemberships - This parent element only appears if the request came from a travel supplier for this travel type, or from a TMC. This element contains HotelMembership child elements for each included membership. - - -
RoomType string Hotel room preference. Values are: DontCare, King, Queen, Double, Twin, Single, Disability - - -
HotelOther string Other Hotel related description. Format: varchar(30) - - -
PreferFoamPillows boolean Whether the user prefers foam pillows. Format: true\false. - - -
PreferCrib boolean Whether the user prefers to have a crib. Format:true\false. - - -
PreferRollawayBed boolean Whether the user prefers to have a rollaway bed. Format:true\false. - - -
PreferGym boolean Whether the user prefers a hotel with a gym. Format:true\false. - - -
PreferPool boolean Whether the user prefers a hotel with a pool. Format:true\false. - - -
PreferRestaraunt boolean Whether the user prefers a hotel with a restaurant. Format:true\false. - - -
PreferWheelchairAccess boolean Whether the user requires wheelchair access. Format: true\false. - - -
PreferAccessForBlind boolean Whether the user requires a room with access for blind guests. Format:true\false. - - -
PreferRoomService boolean Whether the user prefers a hotel with room service. Format:true\false. - - -
PreferEarlyCheckIn boolean Whether the user prefers a hotel with early check in. Format:true\false. - - -

Hotel Memberships

Name Data Type Description Update Create Comments
VendorCode string The code for the vendor that manages the loyalty program. varchar(2) Required Required Must be a Valid Vendor Code for the Membership Type. This list can be made available upon request.
AccountNo string The user's account identifier in the loyalty program. varchar(60) Required Required See Below.
Status string Name of the user's current level in the loyalty program. varchar (100) - - -
StatusBenefits string Description of a benefit of the loyalty program at the current status. - - -
PointTotal string The user's total number of points in the loyalty program. - - -
SegmentTotal string The user's total segments in the loyalty program. - - -
Expiration DateTime The user's expiration date in the loyalty program. - - Min - 01/01/1753, Max - 12/31/9999

CustomFields

The CustomFields parent element contains a CustomField child element for each field.

Name Data Type Description Update Create Comments
CustomField string The value of the custom field. Format: varchar(255) - - -
Name attribute string The name of the custom field. Format: varchar(255) Required Required -

Roles

A list of users associated to a user:

Name Data Type Description Update Create Comments
FirstName string The Arranger/Manager's first name. Format: varchar(60) Cannot Update - -
LastName string The Arranger/Manager's last name. Format: varchar(60) Cannot Update - -
EmailAddress string The Arranger/Manager's email address. Format: varchar(255) Cannot Update - -
LoginId string The Login Id for Arranger/Manager Required Required -
Type attribute string The Arranger/Manager's role. Values are: Arranger, Manager Required Required -
PrimaryIndicatorFlag attribute boolean For Arrangers type, denotes the primary arranger. Format: true\false. - - -

NOTES:

Sponsors

A list of sponsors associated to a user:

Name Data Type Description Update Create Comments
NonEmployeeUserType string The non-employee's user type. Values are: Contractor, Student/Intern, Candidate for Hire, Invitational Traveler, Dependent/Spouse, Board Member, Other Required Required -
SponsorName string The sponsor’s name. Format: varchar(255) Cannot Update - -
SponsorshipStartDate date The sponsorship start date. Format: YYYY-MM-DD Required Required -
SponsorshipEndDate date The sponsorship end date. Format: YYYY-MM-DD Required Required -
LoginID string The sponsor’s name. Format: varchar(255) Required Required -

NOTES:

TSAInfo

The Transportation Security Administration (TSA) details provided.

Name Data Type Description Update Create Comments
Gender string The user's gender. Values are: Male, Female - - -
DateOfBirth date The user’s date of birth. Format: YYYY-MM-DD. Min - 01/01/1900, Max - 06/06/2079 - - -
NoMiddleName boolean Format: true/false - - -
PreCheckNumber string The user’s pre-check number. Format: varchar(255) - - -
RedressNumber string The user’s redress number. Format: varchar(255) - - -

NOTE: NoMiddleName: If the profile has a middle name, NoMiddleName overrides to false

UnusedTickets

A list of unused tickets associated to a user

Name Data Type Description Update Create Comments
Carrier string The vendor’s name. Format: Varchar(255) Required Required -
TicketNumber string The unused ticket number. Format: Varchar(255) Required Required -
RecordLocator string The unused ticket record locator. Format: Varchar(6) - - -
BaseFare string The base fare of the unused ticket. Format: Varchar(255) - - -
Taxes string The taxes for the unused ticket. Format: Varchar(255) - - -
Fees string The fees for the unused ticket. Format: Varchar(255) - - -
Currency string The currency of the unused ticket. Format: Varchar(3) - - -
TicketType string The type of unused ticket. Format: Varchar(1) - - -
IssueDate date The date of issue for the unused ticket. Format: YYYY-MM-DD. - - Min - 01/01/1753, Max - 12/31/9999
ExpirationDate date The date of expiration for the unused ticket. Format: YYYY-MM-DD. - - Min - 01/01/1753, Max - 12/31/9999
Notes string Notes associated to the unused ticket. Format: Varchar(255) - - -

SouthwestUnusedTickets

A list of unused Southwest tickets associated to a user.

Name Data Type Description Update Create Comments
RecordLocator string The unused ticket record locator. Format: Varchar(255) Required - -
TicketAmount string The amount of the unused ticket. Format: Varchar(255) - - -
Currency string The currency of the unused ticket. Format: Varchar(3) - - -
ExpirationDate date The date of expiration for the unused ticket. Format: YYYY-MM-DD. - - Min - 01/01/1753, Max - 12/31/9999

AdvantageMemberships

A list of advantage memberships associated to a user:

Name Data Type Description Update Create Comments
VendorCode string The code for the vendor that manages the membership program. Format: Varchar(2) Required Required -
VendorType string The vendor type. Values are: Air, Rail, Car, Hotel Required Required -
ProgramNumber string The membership program number. Format: Varchar(20) Required Required -
OriginCode string The origin code. Format: Varchar(12) - - -
DestinationCode string The destination code. Format: Varchar(12) - - -
ProgramCode string The program code. Format: Varchar(20) Required Required -
ExpirationDate date Expiration date. Format: YYYY-MM-DD. Min - 01/01/1900, Max - 06/06/2079 - - -
OptionCode string The option code. Format: Varchar(20) - - -
ProgramName string The program name. Format: Varchar(20) Cannot Update - -

NOTES:

Possible Warnings and Error Messages

Error in XML Document

This error message occurs, when the XML is not formatted in such a way that it can be read.

<Error>
  <Message>There is an error in XML document (1, 147).</Message>
  <Server-Time>2017-06-22T16:51:37</Server-Time>
  <Id>3BDBC49E-8793-4515-BA0E-F9C71ADA7330</Id>
</Error>

The best way to find the cause of the error is by taking the body of your message and comparing it against the Travel Profile XSD. You can use free online sites to validate such as https://www.freeformatter.com/xml-validator-xsd.html

Standard Error Codes

The codes and types of messages that can be returned on updates and creates:

CODE Message Type Notes Example
S001 Success Process completed successfully. Success, no errors or warnings reported.
E001 No Access No access to user data. -
E002 Required Field Missing The field noted is required for updates or creates, no changes were made. -
W001 Invalid Regex The given data does not match the expected regex. -
W002 Invalid Length The given data is too long or too short. -
W003 Not Found In Company The given user was not found in the company. -
W004 Duplicate Entry The given data is duplicated and not allowed. -
W005 Duplicate LoginId The given LoginID is duplicated. -
W006 Out of Range The given data is out of range. -
W007 Field is Required The given field cannot be cleared. -
W009 Invalid Account Number Account number check failed due to length, Luhn, etc. -
W010 Invalid Vendor Code Vendor code given is invalid. -
W011 Cannot Change The given field cannot be altered. -
W012 Primary Cell Number Error Data violates one primary cell phone requirement. -
W013 Invalid Custom Field The data provided is invalid for the custom field. -
W014 Invalid Date Range The data provided is outside of acceptable date range. -
W015 Invalid GUID The GUID is invalid. -
W016 Too Many Items There are too many items in the given list. -
W017 No Access to VendorCode The user lacks access to the given vendor code. -

If incorrect API credentials are provided, the service will return the standard response, e.g. 403 Forbidden. In some cases, the API will return additional information when producing a 400, Bad Request, response. It may contain the following codes in the response's body: * EC1 : The user was not found in database. * EC2: The user is not a company admin, or the company ID does not match the user's company ID. * EC3: The user is not an agency admin, the agency company ID is null, or if agency company ID does not match the user's agency company ID. * EC4: If the application's UUID is null, or if the application is configured not to have access to the input travel config.

Examples for Travel Suppliers

Example 1: Get the travel profile for the user associated with the specified OAuth 2.0 access token

Request

GET {InstanceURI}/api/travelprofile/v2.0/profile HTTP/1.1
Authorization: OAuth {access token}

Example 2: Get the travel profile for a user with a specific login ID

Request

GET https://www.concursolutions.com/api/travelprofile/v2.0/profile?userid_type=login&userid_value=cm@example.com HTTP/1.1
Authorization: OAuth {access token}

Examples for TMCs

Example 3: Get the travel profile for the user associated with the specified OAuth 2.0 access token

Request

GET {InstanceURI}/api/travelprofile/v2.0/profile HTTP/1.1
Authorization: OAuth {access token}

Example 4: Get the travel profile for a user with a specific login ID

Request

GET https://www.concursolutions.com/api/travelprofile/v2.0/profile?userid_type=login&userid_value=cm@example.com HTTP/1.1
Authorization: OAuth {access token}

Example 5: Create a new user

Request

POST https://www.concursolutions.com/api/travelprofile/v2.0/profile HTTP/1.1
Authorization: OAuth {access token}

Body

<ProfileResponse xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" Action="Create" LoginId="william.never@email.com">
  <General>
    <FirstName>William</FirstName>
    <LastName>Never</LastName>
    <RuleClass>Default Rule Class</RuleClass>
    <TravelConfigID>555</TravelConfigID>
  </General>
  <Password>password123</Password>
</ProfileResponse>

Example 6: Update a user

Request

POST https://www.concursolutions.com/api/travelprofile/v2.0/profile HTTP/1.1
Authorization: OAuth {access token}

Body

<ProfileResponse xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" Action="Update" LoginId="william.never@email.com">
  <General>
    <FirstName>Bill</FirstName>
  </General>
</ProfileResponse>

Get a list of travel profile summaries

This endpoint provides a list of travel profile summaries that have been updated since the specified date. The response is separated into pages.

Request

GET {InstanceURI}/api/travelprofile/v2.0/summary?LastModifiedDate=2015-01-01T01:00:00 HTTP/1.1
Authorization: OAuth {access token}

Request parameters

All request parameters are optional. Available request parameters are as follows:

Parameter Name Required/Optional Parameter Type Data Type Description
LastModifiedDate Required path string The date and time, in UTC, that the profiles must be updated after to be included in the response. Format: YYYY-MM-DDThh:mm:ss
Page Optional path string The number of pages to retrieve. If the page is outside the number of existing pages, the response elements will be empty
ItemsPerPage Optional path string The number of travel profiles per page. The maximum value is 200. The default value is 200.

Headers

Accept header

application/xml

Authorization header

Authorization: OAuth {access_token}

Where access_token is the OAuth 2.0 access token of the user whose travel profile summaries you want to retrieve. If you want to access company-wide travel profile information, the user account associated with the OAuth 2.0 access token must have an SAP Concur account with one of these roles: Web Services Administrator for Professional or Can Administer for Standard.

Schema

The data model of the response for the GET operation. The complete schema definition is also available here: Travel Profile Summary V2 XSD

<ConnectResponse>
  <Metadata>
    <Paging>
      <TotalPages />
      <TotalItems />
      <Page />
      <ItemsPerPage />
      <PreviousPageURL />
      <NextPageURL />
    </Paging>
  </Metadata>
  <Data>
    <ProfileSummary>
      <Status />
      <LoginID />
      <XmlProfileSyncID />
      <ProfileLastModifiedUTC />
    </ProfileSummary>
  </Data>
</ConnectResponse>

Response

ConnectResponse root element

The ConnectResponse root element contains the General, Telephones, Addresses, DriversLicenses, EmailAddresses, RatePreferences, DiscountCodes, Air, Car, Hotel, and CustomFields child elements. It has the attributes shown in the response class section.

Metadata element

The Metadata parent element contains the Paging child element.

Paging elements

The Paging parent element contains contains the paging information for the response and it contains the following child elements:

Element Name Data Type Description
TotalPages string The total number of pages to return.
TotalItems string The total number of profiles the query returned.
Page string The page number for the set of results in the current response.
ItemsPerPage string The number of items set to display per page.
PreviousPageURL string The URI to the previous page of results. This element will be empty when there are no previous pages.
NextPageURL string The URI to the next set of results. This element will be empty when there are no next pages

Data element

The Data parent element contains a ProfileSummary child element for each included travel profile.

ProfileSummary

The ProfileSummary element contains the profile information for the response and it contains the following child elements:

Element Name Data Type Description
Status string Current status of the user: Active or Inactive.
LoginID string The SAP Concur user login ID.
XMLProfileSyncID string The user's XML Profile Sync ID, if available.
ProfileLastModifiedUTC string The date, in UTC, when the travel profile was last modified. Format: YYYY-MM-DDThh:mm:ss.

Example

This example gets the list of travel profile summaries modified after January 1 2015.

Request

GET {InstanceURI}/api/travelprofile/v2.0/summary?LastModifiedDate=2015-01-01T01:00:00 HTTP/1.1
Authorization: OAuth {access token}

Response

HTTP/1.1 200 OK
Content-Type: application/xml
<ConnectResponse>
  <Metadata>
    <Paging>
      <TotalPages>1</TotalPages>
      <TotalItems>2</TotalItems>
      <Page>1</Page>
      <ItemsPerPage>200</ItemsPerPage>
      <PreviousPageURL />
      <NextPageURL />
    </Paging>
  </Metadata>
  <Data>
    <ProfileSummary>
      <Status>Active</Status>
      <LoginID>mariab@company1.com</LoginID>
      <XmlProfileSyncID>`string`123</XmlProfileSyncID>
      <ProfileLastModifiedUTC>2015-01-01T01:00:00</ProfileLastModifiedUTC>
    </ProfileSummary>
    <ProfileSummary>
      <Status>Inactive</Status>
      <LoginID>peterk@company1.com</LoginID>
      <XmlProfileSyncID>`string`456</XmlProfileSyncID>
      <ProfileLastModifiedUTC>2015-01-01T01:00:00</ProfileLastModifiedUTC>
    </ProfileSummary>
  </Data>
</ConnectResponse>

Travel Profile v1 - Loyalty Program

The loyalty program information for the user, as entered in SAP Concur.

URI

https://www.concursolutions.com/api/travelprofile/v1.0/loyalty

Content Types

Accept Types

Operations

Update Loyalty Program Information

Updates the loyalty program information for the OAuth consumer. Loyalty contains a variety of information about the user's loyalty membership, including:

Travel Suppliers

If the request is sent from a travel supplier with an Pre-2017 Authorization (Deprecated) token for the user, they can set a new loyalty program number. Travel suppliers can only update their own loyalty program information.

Travel Management Companies

If the request is sent by a TMC, the request can update any loyalty program for the OAuth consumer.

Restrictions

This function is only available to travel suppliers who have completed the SAP Concur application review process. Suppliers may post loyalty membership information for their loyalty programs only.

Request

Headers

Authorization Header

Authorization header with OAuth token for valid SAP Concur user. Required.

Accept Header

application/xml

Request Body

This request contains the LoyaltyMembershipUpdate parent element with a Membership child element for each included loyalty program. The Membership element has a UniqueID attribute containing the loyalty program identifier, and the following child elements.

Update Loyalty Program Membership Request Schema

Element Description
VendorCode The code for the vendor that manages the loyalty program. This element is required when the request is sent by a TMC, and is ignored when the request is sent by a travel supplier.
VendorType The type of vendor that manages the loyalty program. Format: A, C or H
A – Air
C – Car
H – Hotel
This element is required when the request is sent by a TMC, and is ignored when the request is sent by a travel supplier.
AccountNo The user's account identifier in the loyalty program.
Status Name of the user's current level in the loyalty program.  Examples: Gold or Premier.
StatusBenefits Description of a benefit of the loyalty program at the current status. Example: You are entitled to free breakfast.
PointTotal The user's total number of points in the loyalty program.
SegmentTotal The user's total segments in the loyalty program.
NextStatus Name or description of next higher status level in the  loyalty program.
PointsUntilNextStatus Loyalty points required to next status level.
SegmentsUntilNextStatus Booking segments to next status level.

XML Example Request From Travel Supplier

POST https://www.concursolutions.com/api/travelprofile/v1.0/loyalty HTTP/1.1
Authorization: OAuth {access token}
<LoyaltyMembershipUpdate>
  <Membership UniqueID="Frequent Flier">
    <AccountNo>1234567890</AccountNo>
    <Status>Gold</Status>
    <StatusBenefits>Early flight check-in.</StatusBenefits>
    <PointTotal>123456</PointTotal>
    <SegmentTotal>150</SegmentTotal>
    <NextStatus>Platinum</NextStatus>
    <PointsUntilNextStatus>100000</PointsUntilNextStatus>
    <SegmentsUntilNextStatus>100</SegmentsUntilNextStatus>
  </Membership>
  <Membership UniqueID="Business Traveler">
    <AccountNo>0987654321</AccountNo>
    <Status>Preferred</Status>
    <StatusBenefits>Free upgrade to Business Class where available.</StatusBenefits>
    <PointTotal>334002</PointTotal>
    <SegmentTotal>340</SegmentTotal>
    <NextStatus>Premier</NextStatus>
    <PointsUntilNextStatus>200998</PointsUntilNextStatus>
    <SegmentsUntilNextStatus>110</SegmentsUntilNextStatus>
  </Membership>
</LoyaltyMembershipUpdate>

XML Example Request From TMC

POST https://www.concursolutions.com/api/travelprofile/v1.0/loyalty HTTP/1.1
Authorization: OAuth {access token}
<LoyaltyMembershipUpdate>
  <Membership UniqueID="Frequent Flier">
    <VendorCode>AA</VendorCode>
    <VendorType>A</VendorType>
    <AccountNo>1234567890</AccountNo>
    <Status>Gold</Status>
    <StatusBenefits>Early flight check-in.</StatusBenefits>
    <PointTotal>123456</PointTotal>
    <SegmentTotal>150</SegmentTotal>
    <NextStatus>Platinum</NextStatus>
    <PointsUntilNextStatus>100000</PointsUntilNextStatus>
    <SegmentsUntilNextStatus>100</SegmentsUntilNextStatus>
  </Membership>
  <Membership UniqueID="Business Traveler">
    <VendorCode>TR</VendorCode>
    <VendorType>C</VendorType>
    <AccountNo>991823728</AccountNo>
    <Status>Preferred</Status>
    <StatusBenefits>Free upgrade to larger car when available.</StatusBenefits>
    <PointTotal>822311</PointTotal>
    <SegmentTotal>340</SegmentTotal>
    <NextStatus>Premier</NextStatus>
    <PointsUntilNextStatus>200998</PointsUntilNextStatus>
    <SegmentsUntilNextStatus>110</SegmentsUntilNextStatus>
  </Membership>
</LoyaltyMembershipUpdate>

Response

Content Types

application/xml

Update Loyalty Program Membership Response Schema

This request will return a LoyaltyMembershipResponse parent element with the following child elements:

Element Description
Status The status of the update request. Format: OK or ERROR
ErrorDescription The details of the error. Only contains data if the Status is ERROR.

XML Example of Successful Response

HTTP/1.1 200 OK
Content-Type: application/xml
<LoyaltyMembershipResponse>
  <Status>OK</Status>
  <ErrorDescription />
</LoyaltyMembershipResponse>

Travel

Travel Services

Overview

The Travel services consists of a set of APIs that provide programmatic access to travel data such as itineraries, travel profiles, travel requests, and travel loyalty program information. These APIs are categorized into three sets of web services:

Itinerary

The Concur Itinerary web service can be used to pro grammatically access travel data such as trips and bookings in the Concur travel system. The Concur Travel system uses this data to match and consolidate bookings it receives from disparate sources and put these into consolidated travelers’ itineraries, providing travelers a convenient way to view their trips in a single itinerary view. Travelers can view their itineraries through mobile applications or other services.

Travel Profile Web Service

The Travel Profile Web Service consists of a set of resources that provide travel profile functionality customized in specific ways for developers, travel suppliers, and travel management companies (TMCs). Depending on who is using this web service, it provides the ability to update travel loyalty information, and subscribe and unsubscribe to travel profile changes.

Travel requests

Concur Travel Request web service is designed to help businesses control expenses by requiring employees to obtain approval before incurring expenses. It provides the ability to view requests and update the workflow for travel requests.

Trip approval

The Trip Approval resource allows clients to approve or reject trips. Clients send the unique identifier for the trip, the approver email and the workflow action to be performed (either approve or reject).

Itinerary API - Overview & Getting Started

Itinerary Service

Overview

The Itinerary API can be used to programmatically access travel data such as trips and bookings in Concur Travel. Concur Travel uses this data to match and consolidate bookings it receives from disparate sources and put these into consolidated travelers’ itineraries, providing travelers a convenient way to view their trips in a single itinerary view. Travelers can view their itineraries through mobile applications or other services.

Version

Version 1.0

Resources

Trip

Booking

Concepts

Itineraries and Trips

The terms itinerary and trip are synonyms. Trip is the name used for the SAP Concur web service resource that represents an itinerary.

Itinerary, Booking Record, and Segment

Who Can Use This Web Service?

TripLink suppliers, travel management companies (TMCs), and SAP Concur clients and third-party developers can use the Itinerary API. The level of access to the data in the Concur Travel system depends on who is accessing it and the SAP Concur products that have been purchased.

Travel Management Companies

SAP Concur Clients and Third-Party Developers

If you would like to start using this web service, please visit: http://www.concur.com/en-us/connect-platform/suppliers or contact the SAP Partner Enablement Team. SAP Concur products are highly configurable, and not all clients will have access to all features.

Some itinerary data may have come from Sabre. SAP Concur encourages you to speak to Sabre about becoming a Sabre Authorized Developer.

Authentication and Authorization

The Itinerary API uses OAuth 2.0 for authenticating users and authorizing access to travel data.

Authorization for TMCs

TMCs can request or send travel bookings in two ways:

The travel supplier can request or send travel bookings by using an OAuth token for the user the travel booking belongs to, generated with the user's involvement.

Configuration

FAQs

When Do I Send Trips Versus Bookings?

The Itinerary API returns the full booking details to the supplier who will provide the booked service. Suppliers that are not the service provider will receive a subset of the possible fields. These vary by the type of booking relative to the type of supplier. For example, Air booking suppliers that are not the supplier will not see the following fields:

How Can We Save Additional Charges for Hotel and Car Segments? What Types of Charges Are Supported?

The Charges element under Car and Hotel segments allow you to save additional charges using Semantics Codes. Refer to the Semantics and Vendor Codes sections under Reference for more information.

What Vendor Codes Can I Use When Sending Hotel and Car Segments?

Refer to the Semantics and Vendor Codes sections for the full list.

Can I View a Trip Posted Through the Itinerary API in the SAP Concur UI?

Yes. The user who owns the trip will see the trip on their home page. If the trip is in the future, it will show under the upcoming trip list. Trips that are ready to expense will show in the expense report list.

When Can a Trip Be Expensed?

Trips can be expensed after the trip is over under the following conditions:

Air segments can be expensed as soon as they have a ticket with a valid coupon, if the company uses the PreExpenseAir option.

Why is My New Booking Not Showing in the UI?

The request returned successfully with HTTP status - 200 OK. Posted bookings are automatically merged with any existing trip with overlapping dates. Most likely, a trip exists with the same dates and the booking has been added to it.

Will Posted Bookings Be Overwritten by Emailed or TripIt Trips?

No.

Will Posted Bookings Merge with Existing Cliqbook or TripIt Trips?

Yes.

Will Posted Trips Merge with Existing Trips?

No.

Best Practices

Reference

The Itinerary Reference documentation includes the following reference information that can be used in conjunction with the Trip Resource API and Booking Resource API documentation. It includes the following reference topics:

Itinerary Data Model

The Itinerary data model defines data elements that are returned or sent when getting, creating, updating, or deleting trips and bookings with the /api/travel/trip/v1.1 and /api/travel/booking/v1.1 resources respectively.

Trips include all bookings in an itinerary whereas a booking includes only a specific segment of an itinerary. It includes the following elements:

Root Elements

Element Name Data Type TripLink Description
id String Y The unique identifier for the trip URI with encrypted ID.
ItineraryInfo Y Parent element with the information about an itinerary for the specified user.
TripId String Y Encrypted trip identifier value.
ItinLocator String Y This element is obsolete and is supported only for backward compatibility.
BookedVia String The booking method for the trip.
BookedByFirstName String Y The first name of the person who booked the trip.
BookedByLastName String Y The last name of the person who booked the trip.
HasOpenBookingPassive String
CancelComments String Y The comments provided if the itinerary is cancelled. Maximum length: 256 characters.
ClientLocator String
TripLinkLocator String
Comments String Y (Description here). Maximum length 512 characters.
DateBookedLocal DateTime Y The date the trip was booked, in the local time of the booking location. Format: YYYY-MM-DDThh:mm:ss
DateCreatedUtc DateTime Y The date that this trip was created, in UTC. Format: YYYY-MM-DDThh:mm:ss
DateModifiedUtc DateTime Y The date when this trip was last modified in UTC format. Format: YYYY-MM-DDThh:mm:ss.
Description String Y The description for this trip. Maximum length 512 characters.
EndDateLocal DateTime Y The end date of the trip in the ending location’s timezone. Format: YYYY-MM-DDThh:mm:ss.
EndDateUtc DateTime Y The end date of the trip, in UTC. Format: YYYY-MM-DDThh:mm:ss
TravelRequestId String
IsPersonal Boolean Y Indicates whether this trip is for business or for leisure. Format: Business, Leisure
ProjectName String The name of the project assiciated with this trip. Maximum length 255 characters.
StartDateLocal DateTime Y The start date of the trip in the starting location’s timezone. Format: YYYY-MM-DDThh:mm:ss.
StartDateUtc DateTime Y The date when this trip started in UTC format. Format: YYYY-MM-DDThh:mm:ss.
TripName String Y Name of the trip. Maximum length 255 characters.
TripStatus unsignedByte Y The status of the trip. This element only appears if the includeCanceledTrips query parameter is used in the request.
UserLoginId Y The user's login to SAP Concur. This element appears only when the OAuth token is associated with a SAP Concur account with one of these roles: Web Services Administrator for Professional or Can Administer for Standard.
Bookings Array Y An array of bookings that contains a Booking child element for each included booking.
Custom Attributes Array
RuleViolations Array N The list of rule violations associated with the itinerary. This parent element contains a RuleViolation child element for each associated rule violation.

Booking Elements

The Bookings parent element contains a Booking child element for each included booking. TripLink suppliers have access only to a subset of the Booking elements. The TripLink column indicates with a Y if a specific element is available for a TripLink supplier. Each booking element contains the following child elements:

Element Data Type TripLink Description
BookingOwner String Y Specifies the tool that supplied the booking to Concur Travel. The possible values are: ConcurTravel, OpenBookingEmail, AmadeusETravel, ConcurConnectAPI, OpenBookingSupplier and TripIt
BookingSource String Y For TMCs: The name of the booking source for this booking. A booking source is a textual name the system uses to track where a booking took place.
For TripLink suppliers: The name of the booking source for this booking. A booking source is a textual name the system uses to track where a booking took place. This could be a GDS, OTA, Vendor Code for Supplier website or Supplier Direct Connect API
Source Y This element is obsolete and is supported only for backward compatibility.
DateBookedLocal DateTime Y The date the booking was created, in the booking location's local time. Format: YYYY-MM-DDThh:mm:ss
DateCreatedUtc DateTime Y The date the booking was created, in UTC. Format: YYYY-MM-DDThh:mm:ss
DateModifiedUtc DateTime Y The date the booking was last modified, in UTC. Format: YYYY-MM-DDThh:mm:ss
FareExpiresEmailDatetimeUtc DateTime
FormOfPaymentName String The name of the form of payment for the booking.
FormOfPaymentType String The type of the form of payment.
LastTicketDateUtc DateTime
PassengerCount Int The total count of passengers for the booking.
RecordLocator String Y The unique identifier for the booking
RetrievedDateUtc
TicketMailingAddress The mailing address for the booked ticket, if available.
TicketPickupLocation The pickup location for the booked ticket, if available
TicketPickupNumber The confirmation number to pick up the booked ticket, if available.
CreditCardType String The type of credit card (for example, Visa/Mastercard/etc.).
CreditCardLastFour String The last four digits of credit card number.
AirfareQuotes Array List of stored airfare quotes for this booking. For more information, see the AirFareQuotes Elements table.
ItinSourceName String The itinerary source. Format: TravelSupplier
AirlineTickets Array List of airline tickets for this booking. For more information, see the AirLine Tickets Elements table.
Charges Array The charges for this booking. For more information, see the Charges Elements table later on this page.
MiscChargeOrders Array An array of miscellaneous charge orders for this booking. This parent element has a MiscellaneousChargeOrders child element for each miscellaneous charge order associated with this booking. For information about the child elements, see the MiscellaneousChargeOrders Elements table later on this page.
Passengers Array Y This parent element contains a Passenger child element for each booked passenger. See the Passengers Elements table for more information about the child elements.
PassPrograms List of Pass Programs for this booking. This parent element has a PassProgram child element for each pass program associated with the booking. For information about the child elements, see the PassProgram Elements table later on this page.
PhoneNumbers List of Phone numbers associated with this booking. This parent element has a PhoneNumberData child element for each phone number associated with the booking. For information about the child elements, see the PhoneNumberData Elements table later on this page.
RailPayments Array List of Rail payments associated with rail segments in this booking. For information about the child elements in the array, see the RailPayments Elements table later on this page.
Segments Y List of Segments in this booking. This parent element contains one or more Air, Car, Hotel, Dining, Ride, Rail, Parking, or Travel parent elements for the booking. The segments are described in the tables below, see Air Booking Elements, Car Booking Elements, Hotel Booking Elements, Dining Booking Elements, Ride Booking Elements, Parking Booking Elements, and Travel Booking Elements.
Delivery String The method this booking was delivered.
WaitListSegments The segments that the traveler is waitlisted for this booking.
Warnings The warnings associated with the booking.
WebAddresses List of web addresses such as emails and pickup URLs associated with this booking.

MiscellaneousChargeOrder Elements

Element Name Data Type TripLink Description
DateCreatedUtc dateTime The date the charge order was created, in UTC. Format: YYYY-MM-DDThh:mm:ss
DateModifiedUtc dateTime The date the charge order was last modified, in UTC. Format: YYYY-MM-DDThh:mm:ss
IssueDate dateTime The date the charge order was issued. Format: YYYY-MM-DDThh:mm:ss
PlatingCarrierNumericCode string Part of the ticket number that indicates the airline code. This is a three digit number. For example: 001=American, 005=Continental, 006=Delta, 012=Northwest
PlatingControlNumber string Part of the ticket number that indicates the ticket control number. Format: Ten digit number.
TotalAmount decimal The total amount of charge orders for the ticket.
TotalAmountCurrency string The 3-letter ISO 4217 currency code for the total charge order amount.

PassProgram Elements

Element Name Data Type TripLink Description
Amount decimal The program amount.
Name string The program name.
Type string The program type.
UserFirstName string The first name of the passenger.
UserLastName string The last name of the passenger.

PhoneNumberData Elements

Element Name Data Type TripLink Description
PassengerRPH integer Indicates the passenger to whom this phone number belongs.
PhoneNumber string The passenger's phone number.
Type string The type of phone number.
Description string The description for the phone number.

RailPayments Elements

Element Name Data Type TripLink Description
RailAdjustment Type The amount adjusted for a rail booking. For information about the RailAdjustment child elements, see the RailAdjustment Elements table later on this page.
RailPayment Type The payment information for a rail booking. For information about the RailPayment child elements, see the RailPayment Elements table later on this page.

RailAdjustment Elements

Element Name Data Type TripLink Description
AdjustmentDateTime dateTime
AdjustmentDateTimeUTC dateTime
AdjustmentType string
DateCreatedUtc dateTime
DateModifiedUtc dateTime
TicketDocumentIdentifier string
TotalAdjustment decimal
TotalAdjustmentCurrency string
Taxes Array This parent element contains a Tax child element for each rail adjustment tax. For more information, see the Tax Elements table later on this page.

RailPayment Elements

Element Name Data Type TripLink Description
BaseFare decimal The base fare of the booking quote.
BaseFareCurrency string The 3-letter ISO 4217 currency code for the total fare.
DateCreatedUtc dateTime The date the quote was created, in UTC. Format: YYYY-MM-DDThh:mm:ss
DateModifiedUtc dateTime The date the quote was last modified, in UTC. Format: YYYY-MM-DDThh:mm:ss
IssueByDate dateTime The date the quote must be issued by. Format: YYYY-MM-DDThh:mm:ss
IssueDateTime dateTime
IssueDateTimeUTC dateTime
TicketDocumentIdentifier string
TicketType string
TotalFare decimal The total price of the booking.
TotalFareCurrency string The 3-letter ISO 4217 currency code for the total fare.
RailCharges array The charges applied by the airline. This parent element contains a Fixed and a Tax child element for each fixed charge and tax from the airline. See the Fixed Elements table and the Tax Elements table.

AirfareQuotes Elements

The AirfareQuotes parent element is an array that contains a Quote child element that contains the following child elements.

Element Name Data Type TripLink Description
BaseFare Decimal
BaseFareCurrency String
BaseFareNuc Decimal
BaseFareNucCurrency String
DateCreatedUtc DateTime
DateModifiedUtc DateTime
Endorsements String
IssueByDate DateTime
TotalFare Decimal
TotalFareCurrency String
AirlineCharges Array This parent element contains a Fixed and a Percent child element for each fixed charge and percent of fixed charge associated with this airfare quote. For information about these child elements, see the Fixed Elements table and the Percent Elements table later on this page.

Passengers Elements

The passenger parent element is the Passengers Element in Booking Elements. This parent element contains a Passenger child element for each booked passenger.

Element Name Data Type Required/Optional TripLink Description
NameFirst String required Y The first name of the passenger.
NameLast String required Y The last name of the passenger.
NameMiddle String optional Y The middle name of the passenger.
NamePrefix String optional Y The name prefix of the passenger.
NameRemark String optional Y Additional details about the passenger's name.
NameSuffix String optional Y The name suffix of the passenger.
NameTitle String optional Y The title of the passenger.
TextName String optional Y The user's full name as entered in the booking tool if different from the name in the database.
FrequentTravelerProgram String optional Y Passenger's loyalty programs

AirlineTickets Elements

The AirlineTickets parent element is an array that contains the following child elements.

Element Name Data Type TripLink Description
AirlineAdjustmentType Type Any adjustment made to the booking. For information about the child elements of AirlineAdjustmentType, see the AirlineAdjustmentType Elements table later on this page.
ManualAirlineTicket Type The manual airline ticket for the booking. For information about the child elements of ManualAirlineTicket, see the ManualAirlineTicket Elements table later on this page.
AirlineTicket Type The airline ticket for the booking. For information about the child elements of AirlineTicket, see the AirlineTicket Elements table later on this page.

AirlineAdjustmentType Elements

Element Name Data Type TripLink Description
AddCollectAmount decimal
AdjustmentDateTime dateTime
AdjustmentDateTimeUTC dateTime
AdjustmentType String
DateCreatedUtc dateTime
DateModifiedUtc dateTime
PassengerName string
PlatingCarrierNumericCode string
PlatingControlNumber string
RecordLocator string
TotalAdjustment decimal
TotalAdjustmentCurrency string
Taxes Array

ManualAirlineTicket Elements

Element Name Data Type TripLink Description
BaseFare decimal
BaseFareCurrency string
DateCreatedUtc dateTime
DateModifiedUtc dateTime
TotalFareTotalFareCurrency decimal
AirlineCharges array The charges applied by the airline. This parent element contains a Fixed and a Tax child element for each fixed charge and tax from the airline. For information about these child elements, see the Fixed Elements table and the Tax Elements table later on this page.

AirlineTicket Elements

Element Name Data Type TripLink Description
AddCollectAmount decimal
AccountingLine string
BaseFare decimal
BaseFareCurrency string
BaseFareNuc decimal
BaseFareNucCurrency string
ComparisonFare decimal
ComparisonFareCurrency string
DateCreatedUtc dateTime
DateModifiedUtc dateTime
Endorsements string
InvoiceNumber string
IssueDateTime dateTime
IssueDateTimeUTC dateTime
IssuingIataAgencyNumber integer
IssuingPseudoCity string
LinearFareConstructor string
MasterTicketNumber string
NameReference string
PassengerName string
PlatingCarrierNumericCode string
PlatingControlNumber string
ProgramCarrierCode string
ProgramMembershipNumber string
RecordLocator string string
SabreDkNumber string string
Ticketless boolean
TicketType string
TotalFare decimal
TotalFareCurrency string
TourIdentifier string
AirlineCharges array A list of airline charges for this ticket. This parent element contains a Fixed child element for each fixed charge from the airline. For information about these child elements, see the Fixed Elements table later on this page.
AirlineTicketCoupons array A list of coupons for this ticket. This parent element has an AirlineTicketCoupon child element for each coupon associated with this airline ticket. For information about these child elements, see the AirlineTicketCoupon Elements table later on this page.
AirlineTicketExchanges array A list of exchanges for this ticket. This parent element has an AirlineTicketExchange child element for each exchange associated with this airline ticket. For information about these child elements, see the AirlineTicketExchange Elements table later on this page.
AirlineTicketFareBreakups array A list of fare breakups for this ticket. This parent element has an AirlineTicketFareBreakup child element for each fare breakup associated with this airline ticket. For information about these child elements, see the AirlineTicketFareBreakup Elements table later on this page.

AirlineTicketCoupons Elements

Element Name Data Type TripLink Description
ClassOfService string
CouponNumber unsignedByte
CouponStatus string
EndCityCode string
FlightNumber string
NotValidAfterDate dateTime
NotValidBeforeDate dateTime
RateCode string
StartCityCode sring
StartDateLocal dateTime
Status string
TicketDesignator string
Vendor string

AirlineTicketExchanges Elements

Element Name Data Type TripLink Description
Amount decimal
AppliedSegment1 unsignedByte
AppliedSegment10 unsignedByte
AppliedSegment2 unsignedByte
AppliedSegment3 unsignedByte
AppliedSegment4 unsignedByte
AppliedSegment5 unsignedByte
AppliedSegment6 unsignedByte
AppliedSegment7 unsignedByte
AppliedSegment8 unsignedByte
AppliedSegment9 unsignedByte
Currency string
OldRecordLocator string
DateModifiedUtc dateTime
PlatingCarrierNumericCode string
PlatingControlNumber string

AirlineTicketFareBreakups Elements

Element Name Data Type TripLink Description
BaseFare decimal
BaseFareCurrency sring
DateCreatedUtc dateTime
DateModifiedUtc dateTime
IssueByDate dateTime
IssueDateTime dateTime
IssueDateTimeUTC dateTime
TicketDocumentIdentifier string
TicketType string
TotalFare decimal
TotalFareCurrency string
Taxes array The charges applied by the airline. This parent element contains a Fixed and a Tax child element for each fixed charge and tax from the airline. For more information, see the Fixed Elements table and the Tax Elements table later on this page.

Fixed Elements

The Fixed element contains the following child elements.

Element Name Data Type TripLink Description
Amount Decimal The total amount for the rate for the booking.
Currency String The 3-letter ISO 4217 currency code for the total amount.
Description String The description for the rate.
IsPaid Boolean Whether the rate has been paid. Format: true/false.
IsPrimary Boolean Indicates whether the charge is the Primary or Main rate. For example, if one of the rates is the actual rate and the rest are penalties, the actual rate should be set as IsPrimary. Only one charge in a set should be primary. Format: true/false.
SemanticsCode String Indicates the charge category for the line item. Refer to the Semantics Codes table for more information.
SemanticsVendorType String The vendor type: H=Hotel, C=Car, A=Air, G=Ground, R=Rail
StartDateLocal DateTime The start date of the booking, in the user's local time. Format: YYYY-MM-DDThh:mm:ss
Vendor String The vendor for the booking charge.
VendorChargeCode String The vendor's code for the charge

Tax Elements

This Tax element contains the following child elements.

Element Name Data Type TripLink Description
TaxAmount Decimal The amount of the tax.
TaxType String The type of the tax.

Percent Elements

The percent of fixed charges. This parent element contains the following child elements:

Element Data Type TripLink Description
Amount Decimal The total amount for the rate for the booking.
Currency string The 3-letter ISO 4217 currency code for the total amount.
Description sring The description for the rate.
IsPaid boolean Whether the rate has been paid. Format: true/false.
IsPrimary boolean Indicates whether the charge is the Primary or Main rate. For example, if one of the rates is the actual rate and the rest are penalties, the actual rate should be set as IsPrimary. Only one charge in a set should be primary. Format: true/false.
SemanticsCode string Indicates the charge category for the line item. Refer to the Semantics Codes table for more information.
SemanticsVendorType string The vendor type: H=Hotel, C=Car, A=Air, G=Ground, R=Rail
StartDateLocal dateTime The start date of the booking, in the user's local time. Format: YYYY-MM-DDThh:mm:ss
Vendor string The vendor for the booking charge.
VendorChargeCode string The vendor's code for the charge

CustomAttributes Elements

The CustomAttributes parent element contains a CustomAttribute child element with the following child elements.

Element Name Data Type TripLink Description
Data String
DisplayTitle String
DisplayValue String
Name String
DataType String
DisplayOnItinerary Boolean
ExternalId Int

RuleViolations Elements

The RuleViolations element contains a list of rule violations associated with the itinerary. This parent element contains a RuleViolation child element for each associated rule violation. The RuleViolation element has the following child elements:

Element Name Data Type TripLink Description
BestGdsPrice Decimal
BestGdsVendor String
BestInternetPrice Decimal
BestInternetVendor String
CompanyReasonCode String
CompanyRuleText String
Currency String
DateEntered DateTime
EndCity String
EndDate DateTime
NumberOfStops Int
QuotedPrice Decimal
RuleAction String
RuleName String
SegmentType String
SelectedOtherAmount Decimal
SelectedOtherAmountType String
StartCity String
StartDate DateTime
TariffPrice Decimal
TravelerComments String
VendorCode String
VendorName String

AirBooking Elements

The Air Booking parent element is the Air Element in the Segments Array in Booking Elements. This parent element contains an Air Booking child element for each booked flight.

Element Data Type TripLink Description
ClassOfService string The class of the booking.
ConfirmationNumber string The record locator or confirmation number for the flight from the airline.
EndCityCode string Y The IATA airport code for the end city of the booking.
EndDateLocal dateTime Y The booking ending time and date, in the booking location's local time. Format: YYYY-MM-DDThh:mm:ss.
For TripLink suppliers: The time portion of this value will be set to T00:00:00 if the request is from a TripLink - Open Booking Air supplier that does not own the booking.
FlightNumber string Y The flight number for the booking.
StartCityCode string Y The IATA airport code for the starting address for the booking.
StartDateLocal dateTime Y The booking starting time and date, in the booking location's local time. Format: YYYY-MM-DDThh:mm:ss.
For TripLink suppliers: The time portion of this value will be set to T00:00:00 if the request is from a TripLink - Open Booking Air supplier that does not own the booking.
Vendor string Y
CancellationNumber string The cancellation number from the vendor. This field should be set when you cancel a segment.
CancellationPolicy string The cancellation policy from the vendor.
Charges Parent Element The charges for this booking. For more information, see the Charges Elements table later on this page.
DateCancelledUtc dateTime The date the booking was cancelled, in UTC. Format: YYYY-MM-DDThh:mm:ss
DateCreatedUtc dateTime The date the booking was created, in UTC. Format: YYYY-MM-DDThh:mm:ss
DateModifiedUtc dateTime The date the booking was modified, in UTC. Format: YYYY-MM-DDThh:mm:ss
EndDateUtc dateTime Y The booking ending time and date, in UTC. Format: YYYY-MM-DDThh:mm:ss.
For TripLink suppliers: The time portion of this value will be set to T00:00:00 if the request is from a TripLink - Open Booking Air supplier that does not own the booking.
EndGate string Y The arrival gate for the booking.
For TripLink suppliers: Will not appear in the response if the request is from a TripLink - Open Booking Air supplier that does not own the booking.
EndTerminal string Y The arrival terminal for the booking.
For TripLink suppliers: Will not appear in the response if the request is from a TripLink - Open Booking Air supplier that does not own the booking.
LegId string The leg ID of the booking. Leg IDs do not change on a connection. For each unique leg ID in the trip, all flights subsequent to the first segment with the same leg ID are connections.
Seats Parent Element The seats for the booking. This parent element contains an AirSeat element for each included seat. For more information, see the AirSeat Elements table later on this page.
StartDateUtc dateTime Y The booking starting time and date, in UTC. Format: YYYY-MM-DDThh:mm:ss.
For TripLink suppliers:The time portion of this value will be set to T00:00:00 if the request is from a TripLink - Open Booking Air supplier that does not own the booking.
StartGate string Y The departure gate for the booking.
For TripLink suppliers: Will not appear in the response if the request is from a TripLink - Open Booking Air supplier that does not own the booking.
StartTerminal string Y The departure terminal for the booking.
For TripLink suppliers: Will not appear in the response if the request is from a TripLink - Open Booking Air supplier that does not own the booking.
Status string The GDS based booking status for the segment such as HK, HL, BK, etc.
TimeZone string Y The time zone of the booking. Format: One of the supported Olson or Windows Time Zones.
AircraftCode string The code for the aircraft type.
Bags string The number of bags included in the booking.
Cabin string The section of the airplane for the booking.
CarbonEmissionLbs decimal The pounds of carbon emission for this booking.
CarbonModel integer The model used to calculate the carbon emissions.
CheckedBaggage string Whether the booking includes checked baggage.
Duration integer The duration of the booked flight.
ETicket string Whether the booking has an e-ticket. Format: Y/N
IsOpenSegment boolean Whether the segment is open. Format: True/False
IsPreferredVendor integer If the airline is marked as a preferred property by the company. Format: True/False
CreditCardType String The type of credit card (for example, Visa/Mastercard/etc.).
CreditCardLastFour String The last four digits of credit card number.
IsUpgradeAllowed boolean Whether the booking can be upgraded. Format: True/False
Meals string The meals included in the booking.
Miles integer The number of miles included in the booking.
Notes string Additional details about the booking.
OpenSegment string Additional information about the open segment.
OperatedByFlightNumber string Flight Number provided by the airline operating the flight on behalf of the booked airline.
OperatedByVendor sring The airline operating the flight on behalf of the booked airline.
OperatedByVendorName string The name of the airline operating the flight on behalf of the booked airline.
Services string The services included in the booking.
SpecialInstructions string Additional instructions regarding the booking. Max Length: 256
UpgradedDateTime dateTime The date and time the booking was upgraded. Format: YYYY-MM-DDThh:mm:ss

AirSeat Elements

Element Data Type Description
PassengerRph integer The passenger assigned to the seat.
SeatNumber string The number of the seat.

CarBooking Elements

The Car Booking parent element is the Car Element in the Segments Array in Booking Elements. This parent element contains a Car Booking child element for each booked car.

Element Data Type TripLink Description
ConfirmationNumber string The confirmation number from the vendor.
EndDateLocal dateTime Y The booking ending time and date, in the booking location's local time. Format: YYYY-MM-DDThh:mm:ss
StartDateLocal dateTime Y The booking starting time and date, in the booking location's local time. Format: YYYY-MM-DDThh:mm:ss
Vendor string The two letter GDS vendor code. See the Car Vendor Codes table for car vendor codes.
CancellationNumber string The cancellation number from the vendor. This field should be set when you cancel a segment.
CancellationPolicy string The cancellation policy from the vendor.
Charges Parent Element The charges for this booking. For more information, see the Charges Elements table.
Currency string The 3-letter ISO 4217 currency code for the booking.
DailyRate decimal The daily rate for the booking.
DateCancelledUtc dateTime The date the booking was cancelled, in UTC. Format: YYYY-MM-DDThh:mm:ss
DateCreatedUtc dateTime The date the booking was created, in UTC. Format: YYYY-MM-DDThh:mm:ss
DateModifiedUtc dateTime The date the booking was modified, in UTC. Format: YYYY-MM-DDThh:mm:ss
EndCityCode string Y The IATA airport code for the ending address for the booking.
EndDateUtc dateTime Y The booking ending time and date, in UTC. Format: YYYY-MM-DDThh:mm:ss
EndLatitude string The latitude for the ending location of the booking.
EndLongitude string The longitude for the ending location of the booking.
Notes string Additional information about the booking.
PhoneNumber string The phone number for the user.
RateCode string The rate code for the booking.
StartCityCode string Y The IATA airport code for the starting address for the booking.
StartDateUtc dateTime Y The booking starting time and date, in UTC. Format: YYYY-MM-DDThh:mm:ss
StartLatitude string The latitude for the starting location of the booking.
StartLongitude string The longitude for the starting location of the booking.
Status string The booking status.
TimeZone string Y The time zone of the booking. Format: One of the supported Olson or Windows Time Zones.
TotalRate decimal The total rate amount of the booking.
VendorName string The name of the vendor. When using the Unknown Vendor Code ($$), this value appears as the vendor in the itinerary.
AirCondition string The character code that indicates if car has air conditioner. R for AC, N for No AC
Body string The character code to indicate how many passengers the car can seat. B for 2-door, D for 4-door, F for Four-wheel drive, J for All Terrain, K for truck, L for Limo, P for pick-up, R for recreation, S for Sport, T for Convertible, V for Van, W for Wagon/Estate, X for special.
Class string Character code to indicate the class of the car (for example, if it is economy, full size, compact, etc.). Varies by Vendor. C for compact, E for economy, F for full size, I for Intermediate, L for Luxury, M for Mini, P for Premium, S for Standard, X for special.
DiscountCode string The discount code used by the company/TMC to get a discounted rate.
CreditCardType String The type of credit card (for example, Visa/Mastercard/etc.).
CreditCardLastFour String The last four digits of credit card number.
DropoffCollectionAddress1 string The AddressLine1 for the dropoff address when the rental service offers dropoff.
DropoffCollectionAddressType string
DropoffCollectionCategory string
DropoffCollectionCity string City for the dropoff address when the rental service offers dropoff.
DropoffCollectionCityCode string The IATA airport code for the dropoff address when the rental service offers dropoff.
DropoffCollectionCountry string The country for the dropoff address when the rental service offers dropoff.
DropoffCollectionLatitude string The latitude for the dropoff address when the rental service offers dropoff.
DropoffCollectionLongitude string The longitude for the dropoff address when the rental service offers dropoff.
DropoffCollectionNumber string
DropoffCollectionPhoneNumber string The phone number for the dropoff address when the rental service offers dropoff.
DropoffCollectionPostalCode string The postal code for the dropoff address when the rental service offers dropoff.
DropoffCollectionState string The state for the dropoff address when the rental service offers dropoff.
EndAddress string The ending address for the booking.
EndAddress2 string The ending address for the booking.
EndCity string Y The ending address for the booking.
EndCloseTime string The closing time for the dropoff location.
EndCountry string Y The ending address for the booking.
EndLocation string The dropoff location.
EndOpenTime string The opening time of the dropoff location.
EndPhoneNumber string The phone number of the dropoff location.
EndPostalCode string The ending address for the booking.
EndState string Y The ending address for the booking.
FrequentTravelerId string The loyalty program ID for the user.
IsUpgradeAllowed boolean Whether the booking can be upgraded. Format: True/False
NumCars unsignedByte The number of cars rented.
NumPersons unsignedByte The number of people including the driver that the rental is for.
PickupDeliveryAddress1 string The AddressLine1 for the pickup address when the rental service offers pickup.
PickupDeliveryAddressType string
PickupDeliveryCategory string
PickupDeliveryCity string The city for the pickup address when the rental service offers pickup.
PickupDeliveryCityCode string The IATA airport code for the pickup address when the rental service offers pickup.
PickupDeliveryCountry string The country for the pickup address when the rental service offers pickup.
PickupDeliveryLatitude string The latitude for the pickup address when the rental service offers pickup.
PickupDeliveryLongitude string The longitude for the pickup address when the rental service offers pickup.
PickupDeliveryNumber string
PickupDeliveryPhoneNumber string The phone number for the pickup address when the rental service offers pickup.
PickupDeliveryPostalCode string The postal code for the pickup address when the rental service offers pickup.
PickupDeliveryState string The state for the pickup address when the rental service offers pickup.
RateType string The rate type for the booking.
SpecialEquipment string Any special equipment required by the renter.
SpecialInstructions string Additional instructions regarding the booking. Max Length: 256
StartAddress string The starting address of the booking.
StartAddress2 string The starting address for the booking.
StartCity string Y The starting address for the booking.
StartCloseTime string The closing time for the pickup location.
StartCountry string Y The starting address for the booking.
StartLocation string The starting location of the booking.
StartOpenTime string The opening time for the pickup location.
StartPostalCode string The starting address for the booking.
StartState string Y The starting address for the booking.
Transmission string The character code that indicates if the car has auto-transmission. A for Auto, M for Manual
UpgradedDateTime dateTime The date and time the booking was upgraded. Format: YYYY-MM-DDThh:mm:ss

Hotel Booking Elements

The Hotel Booking parent element is the Hotel Element in the Segments Array in Booking Elements. This parent element contains a Hotel Booking child element for each booked hotel.

Element Data Type TripLink Description
ConfirmationNumber string The confirmation number from the vendor.
EndDateLocal dateTime Y The booking ending time and date, in the booking location's local time. Format: YYYY-MM-DDThh:mm:ss
Name string The hotel name for the booking.
StartCityCode string Y The IATA airport code for the starting address for the booking.
StartDateLocal dateTime Y The booking starting time and date, in the booking location's local time. Format: YYYY-MM-DDThh:mm:ss
Status string Y The booking status.
Vendor string The two letter GDS vendor code. See the Hotel Codes table for hotel vendor codes.
CancellationNumber string The cancellation number from the vendor. This field should be set when you cancel a segment.
CancellationPolicy string The cancellation policy from the vendor.
Charges Parent Element The charges for this booking. For more information, see the Charges Elements table.
CheckinTime string The check in time for the hotel booking.
CheckoutTime string The check out time for the hotel booking.
Currency string The 3-letter ISO 4217 currency code for the booking.
CreditCardType String The type of credit card (for example, Visa/Mastercard/etc.).
CreditCardLastFour String The last four digits of credit card number.
DailyRate decimal Average per day rate for the hotel. If the rate varies over the duration, it can be specified using the charges model.
DateCancelledUtc dateTime The date the booking was cancelled, in UTC. Format: YYYY-MM-DDThh:mm:ss
DateCreatedUtc dateTime Y The date the booking was created, in UTC. Format: YYYY-MM-DDThh:mm:ss
DateModifiedUtc dateTime Y The date the booking was modified, in UTC. Format: YYYY-MM-DDThh:mm:ss
EndDateUtc dateTime Y The booking ending time and date, in UTC. Format: YYYY-MM-DDThh:mm:ss
HotelPropertyId string The hotel's property ID.
Notes string Additional information about the booking.
NumPersons unsignedByte The number of people the booking is for.
NumRooms unsignedByte The number of rooms the booking is for.
PhoneNumber string The phone number for the booking.
RateCode string The rate code for the booking.
RoomDescription string The room description for the booking. Max Length: 200
RoomType string The room type for the booking.
SpecialInstructions string Additional instructions regarding the booking. Max Length: 256
StartAddress string The starting address of the booking.
StartAddress2 string The starting address for the booking.
StartCity string Y The starting address for the booking.
StartCountry string Y The starting address for the booking.
StartLatitude string The latitude for the starting location of the booking.
StartLongitude string The longitude for the starting location of the booking.
StartPostalCode string The starting address for the booking.
StartState string The starting address for the booking.
StartDateUtc dateTime Y The booking starting time and date, in UTC. Format: YYYY-MM-DDThh:mm:ss
TimeZone string Y The time zone of the booking. Format: One of the supported Olson or Windows Time Zones.
TotalRate string The total rate amount of the booking.
EndCityCode string The IATA airport code for the ending address for the booking.
DiscountCode string The discount code for the booking.
FrequentTravelerId string The traveler’s ID for the frequent traveler reward program.
HadDeposit boolean Whether the booking had a deposit. Format: true/false
IsUpgradeAllowed boolean Whether the booking can be upgraded. Format: true/false
ModificationCode string The code for the modification to the booking.
PartnerMembershipId string The membership ID of the partner associated with the booking.
PassiveType string The type of the booking.
RateAccess string The rate access for the booking.
RateType string The rate type for the booking.
UpgradedDateTime dateTime The date and time the booking was upgraded. Format: YYYY-MM-DDThh:mm:ss
VendorFlags string Semi-colon-delimited list of flags for free hotel service flags. For example, free breakfast (FB), internet (FI), Parking (FP), etc. If they were all present they can be concatenated as - FB;FI;FP;
VendorName string The name of the vendor. When using the Unknown Vendor Code ($$), this value appears as the vendor in the itinerary.

Dining Booking Elements

The Dining Booking parent element is the Dining Element in the Segments Array in Booking Elements. This parent element contains a Dining Booking child element for each booked meal.

Element Date Time TripLink Description
ConfirmationNumber string The confirmation number from the vendor.
CancellationNumber string The cancellation number from the vendor. This field should be set when you cancel a segment.
Charges Parent Element The charges for this booking. For more information, see the Charges Elements table later on this page.
DateCancelledUtc dateTime The date the booking was cancelled, in UTC. Format: YYYY-MM-DDThh:mm:ss
DateCreatedUtc dateTime The date the booking was created, in UTC. Format: YYYY-MM-DDThh:mm:ss
DateModifiedUtc dateTime The date the booking was modified, in UTC. Format: YYYY-MM-DDThh:mm:ss
EndDateLocal dateTime The booking ending time and date, in the booking location's local time. Format: YYYY-MM-DDThh:mm:ss
EndDateUtc dateTime The booking ending time and date, in UTC. Format: YYYY-MM-DDThh:mm:ss
FrequentTravelerId string The loyalty program ID for the user.
IsUpgradeAllowed boolean Whether the booking can be upgraded. Format: true/false
Name string The name of the restaurant. Maximum length: 80
Notes string Additional information about the booking.
NumPersons unsignedByte The number of persons for the booking.
PhoneNumber string The restaurant phone number.
RestaurantId string The booking vendor’s restaurant ID. Maximum length: 50
StartAddress string The restaurant address. Maximum length: 80
StartAddress2 string The restaurant address. Maximum length: 80
StartCity string The restaurant address. Maximum length: 50
StartCountry string The restaurant address.
StartDateLocal dateTime The booking starting time and date, in the booking location's local time. Format: YYYY-MM-DDThh:mm:ss
StartDateUtc dateTime The booking starting time and date, in UTC. Format: YYYY-MM-DDThh:mm:ss
StartLatitude string The latitude of the restaurant.
StartLongitude string The longitude of the restaurant.
StartPostalCode string The restaurant address. Maximum length: 24
StartState string The restaurant address. Maximum length: 50
Status string The status of the segment.
TimeZone string The time zone of the booking. Format: One of the supported Olson or Windows Time Zones.
UpgradedDateTime dateTime The date and time the booking was upgraded. Format: YYYY-MM-DDThh:mm:ss
Vendor string The two letter GDS vendor code.
VendorName string The name of the vendor. When using the Unknown Vendor Code ($$), this value appears as the vendor in the itinerary.

Ride Booking Elements

The Ride Booking parent element is the Ride Element in the Segments Array in Booking Elements. This parent element contains a Ride Booking child element for each booked ride.

Element Data Type TripLink Description
ConfirmationNumber string The confirmation number from the vendor.
EndCityCode string The ending IATA airport code of the booking.
StartCityCode string The starting IATA airport code of the booking.
Vendor string The two letter GDS vendor code. See the Ride Codes table for ride vendor codes. For an unknown vendor, use the code value $$.
CancellationNumber string The cancellation number from the vendor. This field should be set when you cancel a segment.
CancellationPolicy string The cancellation policy from the vendor.
Currency string The 3-letter ISO 4217 currency code for the booking.
DateCancelledUtc dateTime The date the booking was cancelled, in UTC. Format: YYYY-MM-DDThh:mm:ss
DateCreatedUtc dateTime The date the booking was created, in UTC. Format: YYYY-MM-DDThh:mm:ss
DateModifiedUtc dateTime The date the booking was modified, in UTC. Format: YYYY-MM-DDThh:mm:ss
DropoffInstructions string Instructions regarding the booking.
Duration integer The duration of the booking.
EndAddress string The ending address of the booking.
EndAddress2 string The ending address of the booking.
EndCity string The ending address of the booking.
EndCountry string The ending address of the booking.
EndDateLocal dateTime The booking ending time and date, in the booking location's local time. Format: YYYY-MM-DDThh:mm:ss
EndDateUtc dateTime The booking ending time and date, in UTC. Format: YYYY-MM-DDThh:mm:ss
EndLatitude string The latitude for the ending location of the booking.
EndLocation string The ending location of the booking.
EndLocationCode string The ending location code of the booking.
EndLocationName string The ending location name of the booking.
EndLongitude string The longitude of the ending point of the booking.
EndPostalCode string The ending address of the booking.
EndState string The ending address of the booking.
IsPersonal boolean Whether the segment is for personal travel. Format: true/false.
IsUpgradeAllowed boolean Whether the booking can be upgraded. Format: true/false
MeetingInstructions string The instructions for the meeting location of the booking.
Miles integer The number of miles for the booking.
Name string The name on the booking.
Notes string Additional information about the booking.
NumberOfHours double The number of hours of the booking.
NumPersons unsignedByte The number of people included in the booking.
OperatedByVendor string The operated by vendor for the booking.
PassiveCityCode string The passive city code of the booking.
PhoneNumber string The ride vendor phone number.
PickupInstructions string Instructions regarding the booking.
Rate string The rate for the booking.
RateDescription string The rate description for the booking.
RateNotes string The rate notes for the booking.
RateType string The rate type for the booking.
ReservationId string The booking vendor’s reservation ID.
SpecialInstructions string The special instructions for the ride. Max Length: 256
StartAddress string The starting address of the booking.
StartAddress2 string The starting address of the booking.
StartCity string The starting address of the booking.
StartCountry string The starting address of the booking.
StartDateLocal dateTime The booking starting time and date, in the booking location's local time. Format: YYYY-MM-DDThh:mm:ss
StartDateUtc dateTime The booking starting time and date, in UTC. Format: YYYY-MM-DDThh:mm:ss
StartLatitude string The latitude of the booking start location.
StartLocation string The starting location of the booking.
StartLocationCode string The code of the starting location of the booking.
StartLocationName string The name of the starting location of the booking.
StartLongitude string The longitude of the booking start location.
StartPostalCode string The starting address of the booking.
StartState string The starting address of the booking.
Status string The status of the segment.
TimeZone string The time zone of the booking. Format: One of the supported Olson or Windows Time Zones.
UpgradedDateTime dateTime The date and time the booking was upgraded. Format: YYYY-MM-DDThh:mm:ss
VendorName string The name of the vendor. When using the Unknown Vendor Code ($$), this value appears as the vendor in the itinerary.
Charges Parent Element The charges for this booking. For more information, see the Charges Elements table.

Rail Booking Elements

The Rail Booking parent element is the Rail Element in the Segments Array in Booking Elements. This parent element contains a Rail Booking child element for each booked rail segment.

Element Data Type TripLink Description
ConfirmationNumber string The confirmation number from the vendor.
StartDateLocal dateTime Y The starting date of travel for this segment, in the local time of to the starting point. Format: YYYY-MM-DDThh:mm:ss
Amenities string The booked amenities.
Cabin string The cabin identifier.
CancellationNumber string The cancellation number from the vendor. This field should be set when you cancel a segment.
CarbonEmissionLbs decimal The pounds of carbon emission for this booking.
CarbonModel integer The model used to calculate the carbon emissions.
ClassOfService string The class of the booking.
CreditCardType String The type of credit card (for example, Visa/Mastercard/etc.).
CreditCardLastFour String The last four digits of credit card number.
Currency string The 3-letter ISO 4217 currency code for the booking.
DateCancelledUtc dateTime The date the booking was cancelled, in UTC. Format: YYYY-MM-DDThh:mm:ss
DateCreatedUtc dateTime The date the booking was created, in UTC. Format: YYYY-MM-DDThh:mm:ss
DateModifiedUtc dateTime The date the booking was modified, in UTC. Format: YYYY-MM-DDThh:mm:ss
DiscountCode string The discount code for the booking.
Duration integer The duration of the trip booked.
EndCity string The end city for the rail trip.
EndCityCode string The IATA airport code for the end city of the trip.
EndCountry string The country code for the booking.
EndDateLocal dateTime Y The booking ending time and date, in the booking location's local time. Format: YYYY-MM-DDThh:mm:ss
EndDateUtc dateTime Y The booking ending time and date, in UTC. Format: YYYY-MM-DDThh:mm:ss
EndLatitude string The latitude of the ending point of the booking.
EndLongitude integer The longitude of the ending point of the booking.
EndPlatform string The ending platform location of the booking.
EndRailStation string Y The code for the ending station of the booking.
EndRailStationName string Y The name of the ending station of the booking.
ETicket integer The e-ticket number.
FareType string The type of fare on the rail booking.
FrequentTravelerId string The traveler’s ID for the frequent traveler reward program.
IsUpgradeAllowed boolean Whether the booking can be upgraded. Format: true/false
LegId string The trip leg ID.
Meals string The booked meals.
Miles integer The number of miles booked.
Notes string Additional information about the booking.
NumPersons unsignedByte The number of persons booked for the trip.
NumStops unsignedByte The number of stops in the booking.
OperatedByTrainNumber string The train identifier of the operating vendor of the booked trip.
OperatedByVendor string The operating vendor of the booked trip.
RateCode string The vendor's code for the rate of the booking.
RouteRestrictCode string The code to restrict the route of the booking.
SpecialInstructions string The instructions for the booking. Max Length: 256
StartCity string The starting city of the booking.
StartCityCode string Y The IATA airport code for the starting city of the booking.
StartCountry string The starting country of the booking.
StartDateUtc dateTime Y The starting date of travel for this segment, in UTC. Format: YYYY-MM-DDThh:mm:ss
StartLatitude string The latitude of the starting location of the booking.
StartLongitude string The longitude of the starting location of the booking.
StartPlatform string The starting platform location of the booking.
StartRailStation string Y The code of the starting station of the booking.
StartRailStationName string Y The name of the starting station of the booking.
Status string The booking status.
TimeZone string The time zone of the booking. Format: One of the supported Olson or Windows Time Zones.
TotalRate decimal The total rate amount of the booking.
TrainNumber string The number for the booked train.
TrainTypeCode string The code for the type of train used in the booking.
TrainTypeName string The name of the type of train used in the booking.
TransportMode sring The transport mode of the booking.
UpgradedDateTime dateTime The date and time the booking was upgraded. Format: YYYY-MM-DDThh:mm:ss
Vendor string The two letter GDS vendor code.
VendorName string The name of the vendor. When using the Unknown Vendor Code ($$), this value appears as the vendor in the itinerary.
WagonNumber string The wagon number of the train car.
Charges Parent Element The charges for this booking. For more information, see the Charges Elements table.
Seats Parent Element The booked seats. This parent element contains a RailSeat element for each included seat. For more information, see the RailSeat Elements table later on this page.

RailSeat Elements

Element Data Type TripLink Description
Amenities string The amenities for the seat.
BerthPosition string The berth location of the seat.
Deck string Which deck the seat is on.
FacingForward string Whether the seat is facing forward.
FareSpaceComfort string The space around the seat.
PassengerRph integer Which passenger the seat is assigned to.
SeatNumber string The number of the seat.
SeatPosition string The location of the seat.
SpaceType string The type of space around the seat.
Status string The status of the seat booking.
WagonNumber string The number of the wagon the seat is on.
WagonType string The type of wagon the seat is on.

Parking Booking Elements

The Parking Booking parent element is the Parking Element in the Segments Array in Booking Elements. This parent element contains a Parking Booking child element for each booked parking.

Element Data Type TripLink Description
ConfirmationNumber string The confirmation number from the vendor.
StartDateLocal dateTime The starting date of travel for this segment, in the local time of to the starting point. Format: YYYY-MM-DDThh:mm:ss
CancellationNumber string The cancellation number from the vendor. This field should be set when you cancel a segment.
ClassOfService string The class of the booking.
Currency string The 3-letter ISO 4217 currency code for the booking.
DateCancelledUtc dateTime The date the booking was cancelled, in UTC. Format: YYYY-MM-DDThh:mm:ss
DateCreatedUtc dateTime The date the booking was created, in UTC. Format: YYYY-MM-DDThh:mm:ss
DateModifiedUtc dateTime The date the booking was modified, in UTC. Format: YYYY-MM-DDThh:mm:ss
EndDateLocal dateTime The booking ending time and date, in the booking location's local time. Format: YYYY-MM-DDThh:mm:ss
EndDateUtc dateTime The booking ending time and date, in UTC. Format: YYYY-MM-DDThh:mm:ss
FrequentTravelerId string The traveler’s ID for the frequent traveler reward program.
IsUpgradeAllowed boolean Whether the booking can be upgraded. Format: true/false
Notes string Additional information about the booking.
OperatedByVendor string The operating vendor of the booking.
ParkingLocationId string The location of the parking booking.
PhoneNumber string The parking phone number.
Pin string The PIN number for the booking.
RateCode string The vendor's code for the rate of the booking.
StartAddress string The starting address of the booking.
StartAddress2 string The starting address of the booking.
StartCity string The starting address of the booking.
StartCityCode string The IATA airport code for the starting city of the booking.
StartCountry string The starting address of the booking.
StartDateUtc dateTime The starting date of travel for this segment, in UTC. Format: YYYY-MM-DDThh:mm:ss
StartLocation string The parking location.
StartPostalCode string The starting address of the booking. Maximum length: 24
StartState string The starting address of the booking. Maximum length: 50
Status string The booking status.
TimeZone string The time zone of the booking. Format: One of the supported Olson or Windows Time Zones.
TotalRate string The total rate amount of the booking.
UpgradedDateTime dateTime The date and time the booking was upgraded. Format: YYYY-MM-DDThh:mm:ss
Vendor string The two letter GDS vendor code.
VendorName string The name of the vendor. When using the Unknown Vendor Code ($$), this value appears as the vendor in the itinerary.
Charges Parent Element The charges for this booking. For more information, see the Charges Elements table later on this page.

Travel Booking Elements

The Travel Booking parent element is the Travel Element in the Segments Array in Booking Elements. This parent element contains a Travel Booking child element for each booked travel request.

NOTE: This booking type is used by the Concur Travel Request product to store the main destination for the trip without specifying a transport type.

Element Data Type TripLink Description
CancellationNumber string The cancellation number from the vendor. This field should be set when you cancel a segment.
ConfirmationNumber sring The confirmation number from the vendor.
CreditCardType String The type of credit card (for example, Visa/Mastercard/etc.).
CreditCardLastFour String The last four digits of credit card number.
Currency string The 3-letter ISO 4217 currency code for the booking.
DailyRate decimal Average per day rate for the booking. If the rate varies over the duration, it can be specified using the charges model.
DateCancelledUtc dateTime The date the booking was cancelled, in UTC. Format: YYYY-MM-DDThh:mm:ss
DateCreatedUtc dateTime The date the booking was created, in UTC. Format: YYYY-MM-DDThh:mm:ss
DateModifiedUtc dateTime The date the booking was modified, in UTC. Format: YYYY-MM-DDThh:mm:ss
EndAddress string The ending address of the booking.
EndAddress2 sring The ending address of the booking.
EndCity string The ending address of the booking.
EndCityCode string The IATA airport code for the ending city of the booking.
EndCountry string The ending address of the booking.
EndDateLocal dateTime The booking ending time and date, in the booking location's local time. Format: YYYY-MM-DDThh:mm:ss
EndDateUtc dateTime The booking ending time and date, in UTC. Format: YYYY-MM-DDThh:mm:ss
EndLatitude string The latitude for the ending location of the booking.
EndLocation sring The ending location of the booking.
EndLongitude string The longitude of the ending point of the booking.
EndPostalCode string The ending address of the booking.
EndState sring The ending address of the booking.
TransportMode string The transport mode of the booking.
Notes string Additional information about the booking.
NumPersons unsignedByte The number of persons booked for the trip.
PhoneNumber string The booking phone number.
SpecialInstructions sring The instructions for the booking. Max Length: 256
StartAddress string The starting address of the booking.
StartAddress2 string The starting address of the booking.
StartCity sring The starting address of the booking.
StartCityCode string The IATA airport code for the starting city of the booking.
StartCountry string The starting address of the booking.
StartDateLocal dateTime The starting date of travel for this segment, in the local time of to the starting point. Format: YYYY-MM-DDThh:mm:ss
StartDateUtc dateTime The starting date of travel for this segment, in UTC. Format: YYYY-MM-DDThh:mm:ss
StartLatitude string The latitude of the booking.
StartLongitude sring The longitude of the booking.
StartPostalCode string The starting address of the booking. Maximum length: 24
StartState string The starting address of the booking. Maximum length: 50
Status string The booking status.
TimeZone sring The time zone of the booking. Format: One of the supported Olson or Windows Time Zones.
TotalRate decimal The total rate amount of the booking.
Vendor string The two letter GDS vendor code.
VendorName string The name of the vendor. When using the Unknown Vendor Code ($$), this value appears as the vendor in the itinerary.
Charges Parent Element The charges for this booking. For more information, see the Charges Elements table.

Charges Elements

Element Data Type TripLink Description
Percent Parent Element The percent of fixed charges. For more information about the child elements of this parent element, see the Percent Elements table.
Fixed Parent Element The fixed charges. For more information about the child elements of this parent element, see the Fixed Elements table.
Rate Parent Element The rate for the booking. For more information about the child elements of this parent element, see the Rate Elements table.
RateWithAllowance Parent Element The rate for the booking, including any travel allowances. For more information about the child elements of this parent element, see the RateWithAllowance Elements table.

Rate Elements

Element Data Type Description
Amount decimal The total amount for the rate for the booking.
Currency string The 3-letter ISO 4217 currency code for the total amount.
Description string The description for the rate.
IsPaid boolean Whether the rate has been paid. Format: true/false.
IsPrimary boolean Whether the rate is primary. Format: true/false.
NumUnits decimal The number of units expected for the charge. For instance, 3 days
PerUnit string The unit of measure for the charge. Values represent rates like per DAY, WEEK, or MONTH
SemanticsCode string Indicates the charge category for the line item. Refer to the Semantics Codes table for more information.
SemanticsVendorType string The vendor type: H=Hotel, C=Car, A=Air, G=Ground, R=Rail
StartDateLocal dateTime The start date of the booking, in the user's local time. Format: YYYY-MM-DDThh:mm:ss
Vendor string The vendor for the booking charge.
VendorChargeCode string The vendor's code for the charge.

RateWithAllowance Elements

Element Data Type TripLink Description
AllowanceAmount decimal The cost of overage fees when the allowance is exceeded. For example, if the allowance is 5000 miles, the cost could be $0.02 per mile. The overage must be in the same currency as the basic rate.
AllowanceIsUnlimited boolean Whether the allowance is unlimited. Format: true/false.
AllowanceNumUnits decimal The number of units for the allowance associated with the charge. For example, 5000 miles.
AllowanceUnit string The unit of measure for the allowance associated with the charge. For example, a car weekly rate might allow 5000 miles included in the rate.
Amount decimal The total amount for the rate for the booking.
Currency string The 3-letter ISO 4217 currency code for the total amount.
Description string The description for the rate.
IsPaid boolean Whether the rate has been paid. Format: true/false.
IsPrimary boolean Indicates whether the charge is the Primary or Main rate. For example, if one of the rates is the actual rate and the rest are penalties, the actual rate should be set as IsPrimary. Only one charge in a set should be primary. Format: true/false.
NumUnits decimal The number of units expected for the charge. For instance, 3 days.
PerUnit string The unit of measure for the charge. Values represent rates like per DAY, WEEK, or MONTH
SemanticsCode string Indicates the charge category for the line item. Refer to the Semantics Codes table for more information.
SemanticsVendorType string The vendor type: H=Hotel, C=Car, A=Air, G=Ground, R=Rail
StartDateLocal dateTime The start date of the booking, in the user's local time. Format: YYYY-MM-DDThh:mm:ss
Vendor string The vendor for the booking charge.
VendorChargeCode string The vendor's code for the charge.

Car Vendor Codes

Return to Reference topics

The following car vendor codes are used in the Car Booking Elements.

Vendor Code Vendor Name
FA Able
AC Ace
AD Advantage
AL Alamo
LV Allstate
AF Americar
ZU AutoEurope
ZI Avis
CH Charlie
CP Compass
CO Continental
DS Discount
ZR Dollar
ET Enterprise
ED Eurodollar
EP Europcar
FH Falles Hire Cars
FD Ford Dealer
HO Holiday Car
IM Imperial
IA Independent Auto
TS Intl Travel
KG Kemwel Holiday
KN Kenning
LL Localiza
ZW Montgomery Ward
NE Nationwide
ZA Payless
PI Pinellas
BL Red And Blue
RR Rent Rite
RS Resort
ZS Sears
SX Sixt
ZT Thrifty
CC Country Car
TR Triangle
CT TT/Key Services
SV U-Save
CY Carey International
CV Capps Vans
AB All American
EE Exoticar Express
LX Limo Service
MW Midway
NF New Frontier
SL SL I.T.S.
US US Rent a Car
VR Specialty Van
WC West Coast
ZH Simply Wheelz
NU Nu Car Rentals
EY Economy Rent a Car
$$ Unknown Car Vendor
ZM Zoom Rent a Car
ZD Budget
ZE Hertz
ZL National
AU Austrian
DR DER Travel Svcs
EN Vip Car Rental
ML Merlin
EZ Ez Rent A Car
FX Fox
LM L & M Car Rental
SW Southwest
NW New Frontier

Hotel Vendor Codes

Return to Reference topics

Vendor Code Vendor Name
RT AccorHotels
AM Adams Mark
AZ The Ascott Limited
AS All Suites
AR AC Hoteles
AJ AmeriSuites
AN Ana Hotels
AX Anasazi Service
AQ ATA Hotels
AO Atlantis Hotel
AH Aston Hotels
AP Andre Balazs
AC Atel France
BB Bartell Hotels
BW Best Western
BM Biltmore
BU Baymont Inns
CJ Caesar Park
QC Camberly
CA Confortel
CO Camino Real Htls
CV COMO Hotels and Resorts
CE Chalet Susse
CR Clarion
CH CIH Hotels
WX Coast Hotels
CS Classical Hotels
CI Comfort Inns
CD Concord Hotels
WA Waldorf Astoria
BC Boutiquw
CX Country Inn
CL Corus Hotels
DC Dorchester Htls
DE Delta Hotels
DS Design Hotels
FT Grande Hotels
DV De Vere
DA Doral Hotels
DO Dorintresorts
DT Doubletree
DY Doyle Hotels
DR Drury Inns
EE Marriott Exec Ap
EO Econo Lodge
ER Electronic Rep
EU Exclusive Htls
RM Hetras
XH Extra Holidays
FA Fairmont Hotels
FQ Fauriel
FM Fiesta American
FE Forte Hotels
FS Four Seasons
FZ Friendship Inns
FC Rocco Forte
GX Global Conextion
HN Linkhotel
GR Six Senses Hotel
GT Golden Tulip
AG Gouverner Hotel
GN Gramercy Park Hotel
GH Grand Heritage
GD Grand Tradition
HB Hbs Hotel Booki
HX Hampton Inns
HR Harrah's
HV Harvey Hotels
HP Hyatt Place
BH Hawthorn Suites
HL Hilton Intl
BE Homestead Studio
HG Homewood Suites
HO Hotelrez
AI Armani Hotels
HW Hotel World
HQ Hotelink Intl
HA HOTUSA Hotels
MR Morgans Hotel Group
IL Innlink Res Svc
IP InnPoints
IG Insignia Resorts
IC InterContinental
IE InterEurope Htls
IT Intl Trvl Resort
TS Intl Trvl Svcs
IR Innpoints
JA Jarvinen Hotels
JY Jolly Hotels
KA Karos Hotels
KI Kempinski
KY Keytel
KC Kimpton Hotels
KN Kintetsu Intl
NV Las Vegas Travel
LW Leading Hotels
LM Vantis Hotel GRP
LA Little America
LZ Loews Hotels
LR LRI
LU Luxor Hotel
MY Personality Hotels
MZ Mainstay Suites
MO Mandarin Orientl
MH Marco Polo Htls
MM Maritim Hotels
ET Marriott Cnf Ctr
MG Magnolia Hotels
MF Micros Fidelio
MT Microtel Hotels
MU Millennium Htls
MP Mantra Group
MN Montage Hotels A
MI Malmaison Hotels
MK Movenpick Htls
ND National Hotels
NO New Otani
NK Nikko Hotels
NH Nippon Travel
OB Oberoi Group
OC Okura Hotels
OM Omni Hotels
OH Oslo Hotel
OR Outrigger
PS Sandman Hotels
PF Pan Pacific
PL Parkroyal Hotels
PQ Purple Hotels
PH Preferred Hotels
PW Prima Hotels
PN Peninsula Hotels
PR Protea Hotels
QI Quality Inns
QL Queens Hotels
QM Queens Moat Htls
QH QHotels
RD Radisson
NR Ramada Intl
ON Reconline
RL Red Lion Inns
RF Red Roof Inns
RQ Regal Hotels
KR Regal Hotels UK
RE Regent Intl
RH Reservations Hub
BR Renaissance Intl
RC Residence Inns
RR Righa Royal
RZ Ritz-Carlton
RW Rosewood
RI Rodeway Inns
RO Rotana Hotels and Resorts
RB Resort Bookings
RG Rydges Group
SH Scandic Hotels
IQ Myfidelio
SC Sceptre Hotels
SQ Select Hotels
SG Shangri-La
BP Shilo Inns
US Sierra Hotels
SJ Jameson Inns
SZ Sleep Inns
SB Sofitel
LX Small Luxury
SM InnLink Res Svc
SN Sonesta Hotels
ST Sorat Hotels
SP Special Prop-IHG
XV SpringHill Suites
SR Steigenberger
SK Stakis Hotels
YS Stamford Hotels
LV Las Vegas Test
YZ Staybridge Ste
WR Sterling Intl
SS Studio 6
XL Summit Hotels
SX Supranational
UK Swallow Hotels
SL Swissotel
TI Thistle Hotels
TM Tianma
TP Top Intnl Htls
TH Trident Hotels
TO TownePlace Suites
TA Reservhotel
TX Treff Hotels
TR Cendant Trip Rewards
VP VIP Intl
VA OneTech Solution
VI Vienna International
WH W Hotels
DW Walt Disney Htl
WK Warwick Hotels
WL Wellesley Inns
WM Westmark Hotel
EJ Williams
WC WestCoast Hotels
WW World Hotels
WY Wyndham Hotels
SW Starwood (All)
AL Aloft Hotels
BY Banyan Tree
EL Elements
GA Global Alliance
IW Hotels & Preference
QX Luxury Lifestyle
RP Rendezvous Hospitality Group
RU Hard Rock
TY Tradyso Global Distribution
ZX Marriott Affliat
TB GTA TravelBound
DX Dolce Hotels
JI Jurys Inns
LD Leonardo
LJ Lalit
NZ Ascend
IN Indigo Hotels
LC Luxury Collection
LI LeisureLink Inc
OT Othon Hotels
PX Performance Conn
PY Peabody Hotels
SE Sercotel
WF West Coast Famil
ZC Ritz Club
XO Luxury Resorts
AT Address Hotels
CQ Club Quarters
ML Melrose Hotels
DH Distinguished Hotels
PI Premier Inn
ZZ Independent
JT Jumeirah
EZ Cambria Suites
UB Suburban Extended Stay
FB Fontainebleau
GV Graves Hotels
IM Independent Htls
JL Jumeriah
LP Lexington
OP Omni Partners
PV Preferred Group
RJ Resort Condos
RK Rezlink Intl
UV Univisit
VK Vacationclick
VR Vacation Rentals
XN Global Res
XX New Synxis
XZ Hotelzon
OI Amadeus LinkHotel
GF Grange Hotels
EP Epoque Hotels
LO Langham Hotels
PM Barcelo Hotels
QV ResortQuest Intl
XW WebRes
YH Booking Services
YP Altiuspar Soluti
DD Derag Hotels
XR St Regis
6C Intercontinental Hotels Group
AB Abba Hotels
AE AmeriHost Inn
AV Allegience Svcs
AW Astra Worldwide
BA Boscolo Hotels
BG Bulgari Hotels
BN Barcelo Hotels
BV Best Value Inns
CG City Lodge Group
CN Conrad
CP Crowne Plaza
CU Charming Hotels
CW Carlson Brands (All)
CZ Comfort Suites
DI Days Inn
DM Domina Hotels
DU Destinations Unl
EC Choice Brands
EH Hilton (All)
EK Sercotel
EM Marriott (All)
GI Hilton Garden Inn
GM Meritus
GW Great Hotels
HE Historic Hotels
HF HomeGate Studios
HU Hyatt Vacation
ID Resnet
IF ACC-NIFOS
IS Ian Schrager
IU Intourist Travel
JC Cendant Brands (All)
JU Jumer
KL ClubHouse Inns
LT Travelodge AU
MS Magnuson Hotels
MV MGM Mirage
NN Louvre Hotels
NY Denihan Hospitality Group
OE Orient Express
OK Alesia
OS Sweden Hotels
PK Park Plaza Intl
PT Prime Hotels
RA Ramada Hotels
RN Expotel
RX Ringhotels
SO Sonesta
SV Sarova Hotels
SY Starhotels
TL Travelodge
TV ReservHotel
VC Marriott Vacation Club
WD Chase Suite Hotels
WG Wingate Inn
XS Summerfield Suites
II Indecorp
GZ Genares Worldwide
GE Gaylord Hotels
FV Flairview
EW Exclusive World
GQ Genre Hotels
FX First Hotel
WT Tryp by Wyndham
UN Carino Hotels
GP Husa Hotels
IV InnVite
LG Lindner Hotels
JJ Jin Jiang Hotels
CK Black Pepper Hotels
QO Swiss Quality Hotels
AK Autograph
EB Edition
EQ Eaton
FD Etours
HM Missoni
JG JG Black Book
OO One And Only
UA Premier Connect
PU Pullman
QG Quest
TW Trump Hotel Collection
TF Thon Hotels
IA Corinthia Hotels
NU Northwood Hospitality
HC hotel.de
$$ Unknown Hotel Vendor
QU Aqua Hotels and Resorts
FG FastBooking
BL Balladins Hotels
ZW CWT Private Hotels
DN Destination
XE Excalibur
CY Courtyard
ES Embassy Suites
FN Fairfield Inns
HH Hilton
HI Holiday Inn
HJ Howard Johnson
HY Hyatt
MC Marriott
SI Sheraton
WI Westin
CB Classic British
HT Home2 Suites
JH Jumer Hotels
LQ La Quinta Inns
QR Quality Htl Res
SU Southern Sun
UI Utell
PD Park Inn
SF Sutton Place Htl
YO Candlewood Stes
KG Knights Inn
VG Villager
OZ Super 8
VY Maybourne Hotels
JD Doyle Collection
EA Extended Stay
VE Vantis Hotels
YX Synxis Res Svcs
BK Interstate Hotels and Resorts
MD Le Meridien
LE Luxe Worldwide
KH K Hotels
FW Flag Hotels
UZ Unirez
GO Guesthouse International
TG Travelodge UK
WO WorldRes
JV Joie De Vivre
PJ Prince Resorts
BI Best Inns
MB Mandalay Bay
YR Raffles Intl
FH Fiesta Americana
NS NH Hotels
NC Noble House
OG Olympus Hospitality
RS Rockresorts Intl
GB MacDonald Group
WB Relais/Chateaux
GG Grand Hosp.
AA AmericInns
MX Motel 6
DL Doral Resorts
CC Clarion
BT BT Advantage
SA Sabre Exclusives
RV Red Roof Inns
TJ Taj Hotels
BX Columbus Res Svc
BZ Cmnet Brazil
CM Camino Real
DJ Hotel Port
EI Executive Hotels
HK Hot Key Intl.
IH CIH Hotels
KO KSL Resorts
ME Sol Melia
NW Newtrade
PG Phillips Hotel
UE Universal Resort
WS World Res
WV TravelCLICK

Ride Vendor Codes

Return to Reference topics

Vendor Code Vendor Name
$R RideCharge
AL AddisonLee
DG DeemGroundLimo
GC GroundScope
GS GroundSpan
LC Limoscom
SQ SummitQwest
SW SummitQwest
TD Tandem
TV Transvip

Semantics Codes

Return to Reference topics

The semantics codes are used in the Charges child elements in Bookings.

Vendor Type Semantics Code Description
Hotel OTHER Other miscellaneous charges
Hotel BUSINESS Business center charges
Hotel CONFERENCE Conference charges
Hotel COUNTYTAX County tax
Hotel VAT VAT tax
Hotel GST GST tax
Hotel FEDERALTAX Federal tax
Hotel FOOD Food/beverage charges: hotel restaurant, room service
Hotel ALCOHOL Alcohol charges: beer, wine, and liquor at restaurant
Hotel FOODTAX Food/beverage taxes
Hotel GIFT Gift shop charges
Hotel GENERALTAX General taxes
Hotel HEALTH Health club, pool, court, golf, etc.
Hotel LAUNDRY Laundry
Hotel MINIBAR In room mini-bar
Hotel CITYTAX City tax
Hotel MOVIE Movie, in room entertainment
Hotel GAME Game, in room entertainment
Hotel PARKING Parking/Valet
Hotel PST PST tax
Hotel STATETAX State tax
Hotel PAYMENT Payment
Hotel DISCOUNT Discount
Hotel ROOMRATE Room rate
Hotel ROOMTAX Room tax
Hotel GRATUITY Gratutities, tips
Hotel PHONE Telephone charges
Hotel INTERNET Internet charges
Hotel NOSHOW No show fee
Hotel NEGOTIATEDRATE Negotiated room rate
Car DAYS DAYS
Car WEEKS WEEKS
Car MONTHS MONTHS
Car EXTRAHOURS EXTRA HOURS
Car EXTRADAYS EXTRA DAYS
Car EXTRAWEEKS EXTRA WEEKS
Car MILEAGEFEE MILEAGE FEE
Car UPGRADEFEE UPGRADE FEE
Car ADJUSTMENT ADJUSTMENT
Car DISCOUNT DISCOUNT
Car COLLECTION COLLECTION
Car DELIVERY DELIVERY
Car INTERCITY INTERCITY
Car ADDLDRIVER ADDITIONAL DRIVER
Car SERVICECHARGE SERVICE CHARGE
Car LDWCDW LDW/CDW
Car ALIAMOUNT ALI AMOUNT
Car PAIPECAMOUNT PAI/PEC AMOUNT
Car THEFTPROTECT THEFT PROTECTION
Car FUELSERVICE FUEL SERVICE
Car AIRPORTFEE AIRPORT FEE
Car AGEDIFFER AGE DIFFERENTIAL
Car CHILDSEAT CHILD SEAT
Car SKIRACK SKI RACK
Car ADDLSERVICE ADDITIONAL SERVICE
Car OTHERCHARGES OTHER CHARGES
Car TRANSACTIONFEE TRANSACTION FEE
Car SATELLITERADIO SATELLITE RADIO
Car NEVERLOST NEVERLOST
Car ACSURCHARGE A/C SURCHARGE
Car RESERVATIONFEE RESERVATION FEE
Car TAXDIFFER TAX DIFFERENTIAL
Car VOUCHERADJUST VOUCHER ADJUSTMENT
Car VATAMOUNT VAT AMOUNT
Car GSTAMOUNT GST AMOUNT
Car VEHICLELICENSE VEHICLE LICENSE FEE
Car CUSTFACILITY CUSTOMER FACILITY
Car VEHLEASETAX MOTOR VEHICLE LEASE TAX
Car ROADTAX ROAD TAX
Car OTHER OTHER
Car ACRECOVERYFEE AIR CONDITION RECOVERY FEE
Car CONCESSIONFEE CONCESSION PASS THRU FEE
Car CUSTRELATIONS CUSTOMER RELATIONS EXPENSE
Car TFFCORPVRT TFFC OR PVRT
Car IMPOUNDSTORAGE IMPOUND/STORAGE
Car LISAMOUNT LIS AMOUNT
Car SUPLIABILITY SUPPLEMENTAL LIABILITY PROTECTION
Car DROPOFFFEE DROPOFF FEE
Car WEEKEND WEEKEND DAILY RATE
Air OTHER Miscellaneous charge
Air SEGFEE Segment fee
Air SEGFEE_AS_FEE Segment fees as fee
Air SEGFEE_AS_FARE Segment fees as base fare
Air SEGFEE_AS_TAX Segment fee as tax
Air WIRELESS_FEE Wireless Fee
Rail OTHER Miscellaneous charge
Rail TICKET Price of ticket
Rail SEAT Price of seat

Time Zones

Return to Reference topics

SAP Concur converts local date/time to UTC. In order to do that we need to be able to determine where the local time is.

Olson Time Zones

Africa/Cairo Africa/Casablanca Africa/Harare Africa/Luanda
Africa/Nairobi Africa/Windhoek America/Anchorage America/Argentina/Buenos_Aires
America/Asuncion America/Bahia America/Bogota America/Buenos_Aires
America/Caracas America/Chicago America/Chihuahua America/Denver
America/Godthab America/Guyana America/Halifax America/Indianapolis
America/Los_Angeles America/Manaus America/Mexico_City America/Montevideo
America/New_York America/Phoenix America/Regina America/Santiago
America/Sao_Paulo America/St_Johns America/Swift_Current America/Tijuana
Asia/Almaty Asia/Amman Asia/Baghdad Asia/Baku
Asia/Bangkok Asia/Beirut Asia/Calcutta Asia/Colombo
Asia/Damascus Asia/Dhaka Asia/Irkutsk Asia/Jerusalem
Asia/Kabul Asia/Kamchatka Asia/Karachi Asia/Karachi
Asia/Katmandu Asia/Krasnoyarsk Asia/Magadan Asia/Muscat
Asia/Novosibirsk Asia/Rangoon Asia/Riyadh Asia/Seoul
Asia/Shanghai Asia/Singapore Asia/Taipei Asia/Tbilisi
Asia/Tehran Asia/Tokyo Asia/Ulaanbaatar Asia/Vladivostok
Asia/Yakutsk Asia/Yekaterinburg Asia/Yerevan Atlantic/Azores
Atlantic/Cape_Verde Atlantic/South_Georgia Australia/Adelaide Australia/Brisbane
Australia/Darwin Australia/Hobart Australia/Perth Australia/Sydney
Etc/GMT+12 Etc/GMT-11 Etc/GMT-2 Europe/Athens
Europe/Berlin Europe/Helsinki Europe/Istanbul Europe/Kaliningrad
Europe/London Europe/Minsk Europe/Moscow Europe/Paris
Europe/Prague Europe/Sarajevo GMT GMT-1200
Indian/Mauritius Pacific/Apia Pacific/Auckland Pacific/Fiji
Pacific/Guadalcanal Pacific/Guam Pacific/Honolulu Pacific/Tongatapu
UTC

Windows Time Zones

Return to Reference topics

Africa/Cairo Africa/Casablanca Africa/Harare Africa/Luanda
Africa/Nairobi Africa/Windhoek America/Anchorage America/Argentina/Buenos_Aires
America/Asuncion America/Bahia America/Bogota America/Buenos_Aires
America/Caracas America/Chicago America/Chihuahua America/Denver
America/Godthab America/Guyana America/Halifax America/Indianapolis
America/Los_Angeles America/Manaus America/Mexico_City America/Montevideo
America/New_York America/Phoenix America/Regina America/Santiago
America/Sao_Paulo America/St_Johns America/Swift_Current America/Tijuana
Asia/Almaty Asia/Amman Asia/Baghdad Asia/Baku
Asia/Bangkok Asia/Beirut Asia/Calcutta Asia/Colombo
Asia/Damascus Asia/Dhaka Asia/Irkutsk Asia/Jerusalem
Asia/Kabul Asia/Kamchatka Asia/Karachi Asia/Karachi
Asia/Katmandu Asia/Krasnoyarsk Asia/Magadan Asia/Muscat
Asia/Novosibirsk Asia/Rangoon Asia/Riyadh Asia/Seoul
Asia/Shanghai Asia/Singapore Asia/Taipei Asia/Tbilisi
Asia/Tehran Asia/Tokyo Asia/Ulaanbaatar Asia/Vladivostok
Asia/Yakutsk Asia/Yekaterinburg Asia/Yerevan Atlantic/Azores
Atlantic/Cape_Verde Atlantic/South_Georgia Australia/Adelaide Australia/Brisbane
Australia/Darwin Australia/Hobart Australia/Perth Australia/Sydney
Etc/GMT+12 Etc/GMT-11 Etc/GMT-2 Europe/Athens
Europe/Berlin Europe/Helsinki Europe/Istanbul Europe/Kaliningrad
Europe/London Europe/Minsk Europe/Moscow Europe/Paris
Europe/Prague Europe/Sarajevo GMT GMT-1200
Indian/Mauritius Pacific/Apia Pacific/Auckland Pacific/Fiji
Pacific/Guadalcanal Pacific/Guam Pacific/Honolulu Pacific/Tongatapu
UTC

Itinierary API Usage

Itinerary Web Service (TMC/Third-Party)

The SAP Concur Itinerary Web Service allows Travel Management Companies (TMC), SAP Concur clients, and third-party developers to view and create travel related events in the Concur Travel system. TMCs can post bookings for any travel type. This web service can also be used by SAP Concur clients and third-party developers to request trip information for SAP Concur users. The public Itinerary XSD can be found here. In addition, the GetList XSD can be found here.

GET List of Itineraries

Retrieves trip summaries for the traveler specified in the OAuth token. This endpoint can also be used to get details for trips for a different user or the whole company. This is most often done when a Travel Management Company needs to get a list of trips on behalf of a user or company. During the request, a user with one of the following user roles from the user's company must authenticate through OAuth: Web Services Administrator for Professional, or Can Administer for Standard.

The response for this function can be divided into pages for easier processing.

Parameters

Name Description
tripId The trip id
startDate={_date_} The URL-encoded start date (in Coordinated Universal Time, aka UTC) for the trip. Format: YYYY-MM-DD. If no query parameters are provided, the start date is set to today's date - 30 days. The request will only return trips that are ongoing during the provided dates, either starting on the date, or starting before the date and ongoing during the provided date.
endDate****={_date_} The URL-encoded UTC end date for the trip. Format: YYYY-MM-DD. If no query parameters are provided, the end date is set to today's date + 12 months. The request will only return trips that are ongoing during the provided dates, either ending on the date, or starting before the date and ongoing during the provided date.
createdAfterDate****={_date_} The URL-encoded UTC date for when the trip was created. The query string will return trips created on or after this date. Used with the createdBeforeDate for finding trips created during a date range. Format: YYYY-MM-DD.
createdBeforeDate****={_date_} The URL-encoded UTC date for when the trip was created. The query string will return trips created on or before this date. Used with the createdAfterDate for finding trips created during a date range. Format: YYYY-MM-DD.
lastModifiedDate****={_date_} The last modified UTC date of the trips and any their associated bookings. This query string will return only the trips where the trip or any of its associated bookings have a last modified date that is greater or equal to the supplied time. The provided date/time can be anytime between now and the first date of trip creation in the database. The format is either the date or the date and time combined.
bookingType={_type_} The trip includes at least one booking of this type. Format: Air, Car, Dining, Hotel, Parking, Rail, or Ride
userid_type=login&userid_value=_{loginID}_ The loginID is the user's SAP Concur login ID. The userid_value of ALL can be sent to get trip summaries for all users at the company. The userid_type and userid_value parameters can only be used if the OAuth consumer has one of the user roles listed above.
includeMetadata=true&ItemsPerPage={_number_}&Page={_number_} The includeMetadata query parameter combined with the ItemsPerPage and Page query parameters will cause the response to be divided into pages. The response will be wrapped in a ConcurResponse parent element, with both the response details and the paging metadata included. The details of the response are here. If the ItemsPerPage query parameter is not sent, the response will default to 200 if the Page query parameter is sent, or 1000 if the Page query parameter is not set. If the Page query parameter is not sent, the response will default to page 1.
includeVirtualTrip=_1_ Virtual trips are segments booked offline through the Travel Request product. Set the includeVirtualTrip query parameter to 1 to include those trips in the list.
includeCanceledTrips=_{true/false}_ The includeCanceledTrips query parameter will cause the request to also return trips with a status of Canceled. When this query parameter is set to true, the response will include the TripStatus element.

Examples:

To get itinerary list for the entire company (OAuth consumer must have Admin user role):
https://www.concursolutions.com/api/travel/trip/v1.1/?startDate={startdate}&endDate={enddate}&_createdAfterDate={_date}&createdBeforeDate={date}&lastModifiedDate={date}&bookingType={type}&userid_type=login&userid_value=ALL

To get itinerary list for a single user (the OAuth consumer):
https://www.concursolutions.com/api/travel/trip/v1.1/?startDate={startdate}&endDate={enddate}&_createdAfterDate={_date}&createdBeforeDate={date}&lastModifiedDate={date}&bookingType={type}

To get itinerary list for a single user (other than the OAuth consumer):
https://www.concursolutions.com/api/travel/trip/v1.1/?startDate={startdate}&endDate={enddate}&_createdAfterDate={_date}&createdBeforeDate={date}&lastModifiedDate={date}&bookingType={type}&userid_type=login_id&userid_value={loginID}

XML Example Request by Start and End Date

GET /api/travel/trip/v1.1/?startDate=2012%2F02%2F01&endDate=2013%2F12%2F31 HTTP/1.1
Host: www.concursolutions.com
Authorization: OAuth {access token}
...

XML Example Request by Booking Type and Start Date

GET /api/travel/trip/v1.1/?startDate=2012%2F02%2F01&bookingType=Air HTTP/1.1
Host: www.concursolutions.com
Authorization: OAuth {access token}
...

XML Example Request by Created Date

GET /api/travel/trip/v1.1/?createdAfterDate=2012%2F02%2F01 HTTP/1.1
Host: www.concursolutions.com
Authorization: OAuth {access token}

XML Example Request with Paging

GET /api/travel/trip/v1.1/?createdAfterDate=2012%2F02%2F01&includeMetadata=true&ItemsPerPage=2&Page=1 HTTP/1.1
Host: www.concursolutions.com
Authorization: OAuth {access token}

Get List of Itineraries Response

This request will return an ItineraryInfoList parent element with an ItineraryInfo child element for each trip summary for the specified traveler. Each ItineraryInfo element has the following child elements:

Name Description
TripId Encrypted trip identifier value.
TripName Name of the trip
TripStatus The status of the trip. This element only appears if the includeCanceledTrips query parameter is used in the request.
StartDateLocal The start date of the trip in the starting location's timezone. Format: YYYY-MM-DDThh:mm:ss.
EndDateLocal The end date of the trip in the ending location's timezone. Format: YYYY-MM-DDThh:mm:ss.
UserLoginId The user's login to SAP Concur. Only appears when the OAuth consumer has one of the specified admin roles.
DateModifiedUtc The UTC date that this trip was last modified. Format: YYYY-MM-DDThh:mm:ss.
id Trip ID URI with encrypted ID.

Paging

If the includeMetadata and ItemsPerPage query parameters are included in the request, the response will include a ConnectResponse parent element with the following elements:

Name Description
Data This parent element contains the response as detailed above.
Metadata This parent element contains the Paging elements.

Paging Elements

The parent element of the paging information. Contains the following child elements:

Name Description
TotalPages The total number of pages the query returned.
TotalItems The total number of itineraries the query returned.
CurrentPage The page number for the set of results in the current response.
ItemsPerPage The number of items set to display per page.
PreviousPageURL The URI to the previous page of results. This element will be empty when there are no previous pages.
NextPageURL The URI to the next set of results. This element will be empty when there are no next pages.

XML Example of Successful Response

HTTP/1.1 200 OK
Content-Type: application/xml
...

<?xml version="1.0" encoding="utf-8"?>
<ItineraryInfoList xmlns="http://www.concursolutions.com/api/travel/trip/2010/06" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <ItineraryInfo>
        <TripId>naIzQJ0y2DBWjCIQOb2SHTsozwBsHDkdP</TripId>
        <TripName>Trip from Baltimore to New York</TripName>
        <StartDateLocal>2012-02-15T09:00:00</StartDateLocal>
        <EndDateLocal>2012-02-21T17:30:00</EndDateLocal>
        <UserLoginId>cm@example.com</UserLoginId>
        <DateModifiedUtc>2012-02-14T17:13:07</DateModifiedUtc>
        <id>https://www.concursolutions.com/api/travel/trip/v1.1/naIzQJ0y2DBWjCIQOb2SHTsozwBsHDkdP</id>
    </ItineraryInfo>
    <ItineraryInfo>
        <TripId>I2uwiJJw8r7Owl3IWlSie9WIelxhAhwiL</TripId>
        <TripName>Trip from Baltimore to Seattle</TripName>
        <StartDateLocal>2012-03-26T09:00:00</StartDateLocal>
        <EndDateLocal>2012-03-29T17:30:00</EndDateLocal>
        <DateModifiedUtc>2012-03-24T19:00:00</DateModifiedUtc>
        <UserLoginId>cm@example.com</UserLoginId>
        <id>https://www.concursolutions.com/api/travel/trip/v1.1/I2uwiJJw8r7Owl3IWlSie9WIelxhAhwiL</id>
    </ItineraryInfo>
</ItineraryInfoList>

XML Example of Successful Response with Paging

HTTP/1.1 200 OK
Content-Type: application/xml
...

<ConnectResponse>
    <Metadata>
        <Paging>
            <TotalPages>38</TotalPages>
            <TotalItems>187</TotalItems>
            <CurrentPage>2</CurrentPage>
            <ItemsPerPage>2</ItemsPerPage>
            <PreviousPageURL>https://www.concursolutions.com/api/travel/trip/v1.1/?createdAfterDate=2012%2F02%2F01&amp;itemsPerPage=5&amp;page=3&amp;includeMetaData=true</PreviousPageURL>
            <NextPageURL>https://www.concursolutions.com/api/travel/trip/v1.1/?createdAfterDate=2012%2F02%2F01&amp;itemsPerPage=5&amp;page=1&amp;includeMetaData=true</NextPageURL>
        </Paging>
    </Metadata>
    <Data>
        <ItineraryInfoList xmlns="http://www.concursolutions.com/api/travel/trip/2010/06" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
            <ItineraryInfo>
                <TripId>naIzQJ0y2DBWjCIQOb2SHTsozwBsHDkdP</TripId>
                <TripName>Trip from Baltimore to New York</TripName>
                <StartDateLocal>2012-02-15T09:00:00</StartDateLocal>
                <EndDateLocal>2012-02-21T17:30:00</EndDateLocal>
                <UserLoginId>cm@example.com</UserLoginId>
                <DateModifiedUtc>2012-02-14T17:13:07</DateModifiedUtc>
                <id>https://www.concursolutions.com/api/travel/trip/v1.1/naIzQJ0y2DBWjCIQOb2SHTsozwBsHDkdP</id>
            </ItineraryInfo>
            <ItineraryInfo>
                <TripId>I2uwiJJw8r7Owl3IWlSie9WIelxhAhwiL</TripId>
                <TripName>Trip from Baltimore to Seattle</TripName>
                <StartDateLocal>2012-03-26T09:00:00</StartDateLocal>
                <EndDateLocal>2012-03-29T17:30:00</EndDateLocal>
                <DateModifiedUtc>2012-03-24T19:00:00</DateModifiedUtc>
                <UserLoginId>cm@example.com</UserLoginId>
                <id>https://www.concursolutions.com/api/travel/trip/v1.1/I2uwiJJw8r7Owl3IWlSie9WIelxhAhwiL</id>
            </ItineraryInfo>
        </ItineraryInfoList>
    </Data>
</ConnectResponse>

GET Itinerary Details

Retrieves the details for the specified trip. By default, the OAuth consumer should be the owner of the trip. This endpoint can also be used to get details for trips that the OAuth consumer does not own. This is most often done when a Travel Management Company needs to get trip details on behalf of a user. The TMC must be registered with SAP Concur and have a SAP Concur account that has one of the following user roles: Web Services Administrator for Professional, or Can Administer for Standard.

The returned elements will vary based on the following conditions:

This documentation contains the full set of possible elements that can be returned. No itinerary can contain all of the possible elements, so the response will always be a subset of the possible returned values.

Parameters

Name Description
{_tripId_} Required. The identifier for the desired trip.
userid_type=login&userid_value=_{loginID}_ The loginID is the user's SAP Concur login ID. The userid_value of ALL can be sent to get trip summaries for all users at the company. The userid_type and userid_value parameters can only be used if the OAuth consumer has one of the user roles listed above.
systemFormat=_{format}_ The systemFormat query parameter can be used to specify that the response is formatted for a different system. The supported value is Tripit.

Get Itinerary Details Response

This request will return an Itinerary parent element with a subset of the following child elements:

Parameters

Name Description
BookedByFirstName The first name of the person who booked the trip.
BookedByLastName The last name of the person who booked the trip.
BookedVia The booking method for the trip.
CancelComments The comments provided if the itinerary is cancelled. Maximum length: 256 characters.
Comments Optional comments. Maximum length: 512 characters.
DateBookedLocal The date the trip was booked, in the local time of the booking location. Format: YYYY-MM-DDThh:mm:ss
DateCreatedUtc The date that this trip was created, in UTC. Format: YYYY-MM-DDThh:mm:ss
DateModifiedUtc The date that this trip was last modified, in UTC. Format: YYYY-MM-DDThh:mm:ss
Description The trip description. Maximum length: 512 characters.
EndDateLocal The end date of the trip in the ending location's timezone. Format: YYYY-MM-DDThh:mm:ss
EndDateUtc The end date of the trip, in UTC. Format: YYYY-MM-DDThh:mm:ss
IsPersonal Whether the trip is a Business or Leisure trip. Format: true/false.
ProjectName The associated project name for the trip. Maximum length: 255 characters.
StartDateLocal The start date of the trip in the starting location's timezone. Format: YYYY-MM-DDThh:mm:ss
StartDateUtc The start date of the trip, in UTC. Format: YYYY-MM-DDThh:mm:ss
TripName Name of the trip. Maximum length: 255 characters.
Bookings This parent element will contain a Booking child element for each booking associated with this itinerary. Refer to the Booking Child Elements table.
RuleViolations The list of rule violations associated with the itinerary. This parent element contains a RuleViolation child element for each associated rule violation. Refer to the Public Itinerary XSD for more information.
Status The status of the itinerary. One of the following: 0 = Confirmed; 1 = Ticketed by agent; 2 = Canceled

Booking Child Elements

Name Description
BookingSource The name of the booking source for this booking. A booking source is a textual name the system uses to track where a booking took place.
DateBookedLocal The date the booking was created, in the booking location's local time. Format: YYYY-MM-DDThh:mm:ss
DateCreatedUtc The date the booking was created, in UTC. Format: YYYY-MM-DDThh:mm:ss
DateModifiedUtc The date the booking was last modified, in UTC. Format: YYYY-MM-DDThh:mm:ss
FormOfPaymentName The name of the form of payment for the booking.
FormOfPaymentType The type of the form of payment.
PassengerCount The number of passengers included in the booking.
RecordLocator Record locator for this booking. This is often six alphanumeric characters but can have other formats depending on the booking source.
RetrievedDateUtc The date the booking was last accessed, in UTC. Format: YYYY-MM-DDThh:mm:ss
TicketMailingAddress The mailing address for the booked ticket, if any.
TicketPickupLocation The pickup location for the booked ticket, if any.
TicketPickupNumber The confirmation number to pick up the booked ticket, if any.
AirfareQuotes List of stored airfare quotes. This parent element has a Quote child element for each airfare quote. The Quote parent element contains Airfare Quotes Child Elements
AirlineTickets List of Airline Tickets. This parent element contains Airline Tickets Child Elements
Charges The charges for the booking.
MiscChargeOrders This parent element has a MiscellaneousChargeOrder child element for each included miscellaneous charge. The MiscellaneousChargeOrder parent element contains Miscellaneous Charge Order Child Elements
Passengers This parent element has a Passenger child element for each included passenger. Refer to the Passenger Child Elements
PassPrograms This parent element has Pass Program child elements for each pass program associated with the booking.
PhoneNumbers This parent element has Phone Number Data child elements for each phone number associated with the booking.
RailPayments This parent element has Rail Payment Child Elements
Segments This parent element will contain at least one of the following child elements: Air, Car, Hotel, Dining, Ride, Rail, Parking.
Delivery The method used to deliver this booking. Refer to the Delivery Method Child Elements
WaitListSegments Information will appear in this element if the segment is on a waiting list.
Warnings The warnings associated with the booking.
WebAddresses List of web addresses. This parent element includes Web Address Data child elements for each associated web address.
BookingReferrer BookingReferrer is used only in specific source tracking scenarios when there is a need to distinguish between bookings with the same BookingSources coming through different flows. Do not populate without coordinating with your technical contact. The supported values are: Concur Travel, Sign-in with SAP Concur, Supplier Mobile, Supplier Web.

Airfare Quotes Child Elements

Name Description
BaseFare The base fare of the booking quote.
BaseFareCurrency The 3-letter ISO 4217 currency code for the booking quote.
BaseFareNuc The base fare in NUC.
BaseFareNucCurrency The 3-letter ISO 4217 currency code for the base fare in NUC.
DateCreatedUtc The date the quote was created, in UTC. Format: YYYY-MM-DDThh:mm:ss
DateModifiedUtc The date the quote was last modified, in UTC. Format: YYYY-MM-DDThh:mm:ss
Endorsements Notes from the airline if it endorses the ticket as acceptable on a different airline.
IssueByDate The date the quote must be issued by. Format: YYYY-MM-DDThh:mm:ss
TotalFare The total price of the booking.
TotalFareCurrency The 3-letter ISO 4217 currency code for the total fare.
AirlineCharges The charges applied by the airline. This parent element contains a Fixed child element for each fixed charge from the airline.
Taxes The taxed applied to this airline ticket.

Airline Tickets Child Elements

Name Description
ManualAirlineTicket The manual airline ticket for the booking.
AirlineTicket The airline ticket for the booking.
AirlineAdjustment Any adjustment made to the booking.

Miscellaneous Charge Order Child Elements

Name Description
DateCreatedUtc The date the charge order was created, in UTC. Format: YYYY-MM-DDThh:mm:ss
DateModifiedUtc The date the charge order was last modified, in UTC. Format: YYYY-MM-DDThh:mm:ss
IssueDate The date the charge order was issued. Format: YYYY-MM-DDThh:mm:ss
PlatingCarrierNumericCode Part of the ticket number that indicates the airline code. This is a three digit number. For example: 001=American, 005=Continental, 006=Delta, 012=Northwest
PlatingControlNumber Part of the ticket number that indicates the ticket control number. Format: Ten digit number.
TotalAmount The total amount of charge orders for the ticket.
TotalAmountCurrency The 3-letter ISO 4217 currency code for the total charge order amount.

Pass Programs Child Elements

Name Description
Amount The program amount.
Name The program name.
Type The program type.
UserFirstName The first name of the passenger.
UserLastName The last name of the passenger.

Phone Number Data Child Elements

Name Description
PassengerRPH Indicates the passenger to whom this phone number belongs.
PhoneNumber The passenger's phone number.
Type The type of phone number.
Description The description for the phone number.

Rail Payments Child Elements

Name Description
RailPayment The payment information for a rail booking.
RailAdjustment The amount adjusted for a rail booking. Refer to the Public Itinerary XSD for more information.

Delivery Method Child Elements

Name Description
LocationAdditionalDetails Additional information about the delivery location.
AddressLine1 The delivery address.
AddressLine2 The delivery address.
City The delivery address.
Country The delivery address.
LocationDesc Description of the delivery location.
Email The delivery email contact.
Latitude The delivery address.
Longitude The delivery address.
LocationName The name of the delivery location.
PhoneNumber The phone number of the delivery contact.
ReferenceNumber The reference number for the delivery.
State The delivery address.
Type The type of delivery address.
Zip The delivery address.

Web Address Data Child Elements

Name Description
PassengerRPH Indicates the passenger to whom this web address belongs.
WebAddress Web address. Format: email address or URL. Maximum length: 250 characters.
Format Format of the web address. Format: E=Email, U=URL, I=IM
Type Type code for web address. Format: TKT, RES, BUS
Description Free text describing the web address. Maximum length: 50 characters.

Passenger Child Elements

Name Description
FirstNameNumber The number of characters in the passenger's first name.
LastNameNumber The number of characters in the passenger's last name.
NameFirst The passenger's first name.
NameLast The passenger's last name.
NameMiddle The passenger's middle name.
NamePrefix The passenger's name prefix.
NameRemark Additional details about the passenger's name.
NameSuffix The passenger's name suffix.
NameTitle The passenger's name title.
TextName The user's full name.
FrequentTravelerProgram The passenger's loyalty program identifier. This parent element contains the FrequentFlyer and RailProgram child elements.
FrequentFlyer The passenger's frequent flyer program details. This parent element has Frequent Flyer Child Elements
RailProgram The passenger's rail loyalty program details. This parent element has Rail Program Child Elements

Frequent Flyer Child Elements

Name Description
AirlineVendor The vendor of the frequent flyer program.
Description The program description.
DiscountProgramExpirationDate The date the discount program enrollment expires. Format: YYYY-MM-DDThh:mm:ss
DiscountProgramType The type of discount program.
FrequentFlyerNumber The passenger's identifier for the program.
ProgramVendor The program vendor.
Status The passenger's program status.
StatusExpirationDate The expiration date for the passenger's program status.

Rail Program Child Elements

Name Description
Description Description of the discount program.
DiscountProgramExpirationDate The date the discount program enrollment expires. Format: YYYY-MM-DDThh:mm:ss
DiscountProgramType The type of discount program.
ProgramNumber The passenger's identifier for the program.
ProgramVendor The program vendor.
Status The passenger's program status.
StatusExpirationDate The expiration date for the passenger's program status.

XML Example of Successful Response

HTTP/1.1 200 OK
Content-Type: application/xml
...

<?xml version="1.0" encoding="utf-8"?>
<Itinerary xmlns="http://www.concursolutions.com/api/travel/trip/2010/06">
    <id>https://www.concursolutions.com/api/travel/trip/v1.1/CNQR1234567890</id>
    <ItinLocator>CNQR1234567890</ItinLocator>
    <ClientLocator>KK-CNQ-1M1P6-5HJ</ClientLocator>
    <ItinSourceName>ConcurTravel</ItinSourceName>
    <TripName>Trip from Dallas to Seattle</TripName>
    <Comments />
    <StartDateLocal>2013-12-21T07:25:00</StartDateLocal>
    <EndDateLocal>2013-12-24T23:59:00</EndDateLocal>
    <DateModifiedUtc>2012-07-24T19:15:52</DateModifiedUtc>
    <BookedVia>EveryGDS</BookedVia>
    <BookedByFirstName>Chris</BookedByFirstName>
    <BookedByLastName>Miller</BookedByLastName>
    <DateBookedLocal>2012-07-24T19:15:52</DateBookedLocal>
    <Bookings>
        <Booking>
            <Segments>
                <Car>
                    <Vendor>CQ</Vendor>
                    <Status>HK</Status>
                    <StartDateLocal>2013-12-21T12:00:00</StartDateLocal>
                    <EndDateLocal>2013-12-24T12:00:00</EndDateLocal>
                    <ConfirmationNumber>F1672664579</ConfirmationNumber>
                    <DateModifiedUtc>2012-07-24T19:15:52</DateModifiedUtc>
                    <StartCityCode>SEA</StartCityCode>
                    <EndCityCode>SEA</EndCityCode>
                    <StartLocation>SEA</StartLocation>
                    <EndLocation>SEA</EndLocation>
                    <Class>E</Class>
                    <Body>C</Body>
                    <Transmission>M</Transmission>
                    <AirCondition>R</AirCondition>
                    <NumCars>1</NumCars>
                    <DiscountCode>346660</DiscountCode>
                    <DailyRate>44.0000</DailyRate>
                    <TotalRate>44.0000</TotalRate>
                    <RateType>D</RateType>
                    <Currency>USD</Currency>
                    <Charges>
                        <Fixed>
                            <Description>Dropoff Fee</Description>
                            <Currency>USD</Currency>
                            <Amount>0.0000</Amount>
                            <IsPrimary>false</IsPrimary>
                            <SemanticsCode>DROPOFFFEE</SemanticsCode>
                            <SemanticsVendorType>C</SemanticsVendorType>
                        </Fixed>
                        <RateWithAllowance>
                            <Currency>USD</Currency>
                            <Amount>44.0000</Amount>
                            <StartDateLocal>2013-12-21T12:00:00</StartDateLocal>
                            <IsPrimary>true</IsPrimary>
                            <SemanticsCode>DAYS</SemanticsCode>
                            <SemanticsVendorType>C</SemanticsVendorType>
                            <PerUnit>DAY</PerUnit>
                            <NumUnits>1.0000</NumUnits>
                            <AllowanceNumUnits>250.0000</AllowanceNumUnits>
                            <AllowanceAmount>0.2400</AllowanceAmount>
                            <AllowanceIsUnlimited>false</AllowanceIsUnlimited>
                        </RateWithAllowance>
                    </Charges>
                </Car>
            </Segments>
            <Passengers>
                <Passenger>
                    <NameFirst>Chris</NameFirst>
                    <NameLast>Miller</NameLast>
                </Passenger>
            </Passengers>
            <RecordLocator>C123456789</RecordLocator>
            <BookingSource>ConcurCars</BookingSource>
            <DateModifiedUtc>2012-07-24T19:15:52</DateModifiedUtc>
            <DateBookedLocal>2013-11-10T13:01:00</DateBookedLocal>
            <ItinSourceName>TravelSupplier</ItinSourceName>
            <PassengerCount>1</PassengerCount>
        </Booking>
        <Booking>
            <Segments>
                <Hotel>
                    <Vendor>CQ</Vendor>
                    <Status>GK</Status>
                    <StartDateLocal>2013-12-21T23:59:00</StartDateLocal>
                    <EndDateLocal>2013-12-24T23:59:00</EndDateLocal>
                    <ConfirmationNumber>3364214265</ConfirmationNumber>
                    <DateModifiedUtc>2012-07-24T19:15:52</DateModifiedUtc>
                    <RateCode>LV4</RateCode>
                    <Name>CONCUR HOTEL</Name>
                    <HotelPropertyId>CONQ</HotelPropertyId>
                    <CheckinTime>00:00</CheckinTime>
                    <CheckoutTime>00:00</CheckoutTime>
                    <NumPersons>1</NumPersons>
                    <NumRooms>1</NumRooms>
                    <CancellationPolicy>Cxl 1 day prior to Arrival</CancellationPolicy>
                    <DailyRate>240.3500</DailyRate>
                    <Currency>USD</Currency>
                    <RoomDescription>1 KING BED ACCESSIBLE ROOM - K1RRC</RoomDescription>
                    <Charges>
                        <Rate>
                            <Currency>USD</Currency>
                            <Amount>240.3500</Amount>
                            <StartDateLocal>2013-12-21T23:59:00</StartDateLocal>
                            <IsPrimary>false</IsPrimary>
                            <SemanticsCode>ROOMRATE</SemanticsCode>
                            <SemanticsVendorType>H</SemanticsVendorType>
                            <PerUnit>DAY</PerUnit>
                            <NumUnits>3.0000</NumUnits>
                        </Rate>
                    </Charges>
                </Hotel>
            </Segments>
            <Passengers>
                <Passenger>
                    <NameFirst>Chris</NameFirst>
                    <NameLast>Miller</NameLast>
                </Passenger>
            </Passengers>
            <RecordLocator>0987654321</RecordLocator>
            <BookingSource>ConcurHotel</BookingSource>
            <DateModifiedUtc>2012-07-24T19:15:52</DateModifiedUtc>
            <DateBookedLocal>2013-11-10T13:01:00</DateBookedLocal>
            <OriginalItinLocator>33491211</OriginalItinLocator>
            <ItinSourceName>ConcurTravel</ItinSourceName>
            <PassengerCount>1</PassengerCount>
        </Booking>
    </Bookings>
</Itinerary>

XML Response in TripIt Format

<?xml version="1.0" encoding="utf-8"?>
<Response>
    <Trip>
        <id>73014481752</id>
        <relative_url>/api/travel/trip/v1.1/73014481752</relative_url>
        <start_date>2013-08-21</start_date>
        <end_date>2013-08-24</end_date>
        <display_name>Strategy Team meeting</display_name>
        <is_private>true</is_private>
    </Trip>
    <AirObject>
        <booking_site_conf_num>RL10001005</booking_site_conf_num>
        <booking_site_name>Concur Travel</booking_site_name>
        <booking_site_phone></booking_site_phone>
        <booking_site_url>https://www.concursolutions.com</booking_site_url>
        <record_locator>4294993825</record_locator>
        <supplier_conf_num>CN10001005</supplier_conf_num>
        <supplier_contact></supplier_contact>
        <supplier_email_address></supplier_email_address>
        <supplier_name></supplier_name>
        <supplier_phone></supplier_phone>
        <supplier_url></supplier_url>
        <is_purchased>1</is_purchased>
        <notes></notes>
        <restrictions></restrictions>
        <total_cost></total_cost>
        <Segment>
            <StartDateTime>
                <date>2013-08-21</date>
                <time>07:45:00</time>
            </StartDateTime>
            <EndDateTime>
                <date>2013-08-21</date>
                <time>13:03:00</time>
            </EndDateTime>
            <start_airport_code>PHX</start_airport_code>
            <start_gate>A11</start_gate>
            <start_terminal>4</start_terminal>
            <end_airport_code>ORD</end_airport_code>
            <end_gate>F8</end_gate>
            <end_terminal>2</end_terminal>
            <marketing_airline>US</marketing_airline>
            <marketing_flight_number>1</marketing_flight_number>
            <aircraft>320</aircraft>
            <duration></duration>
            <distance>1433</distance>
            <notes></notes>
            <seats></seats>
            <service_class>Economy</service_class>
            <stops>Nonstop</stops>
        </Segment>
        <Segment>
            <StartDateTime>
                <date>2013-08-24</date>
                <time>13:55:00</time>
            </StartDateTime>
            <EndDateTime>
                <date>2013-08-24</date>
                <time>16:58:00</time>
            </EndDateTime>
            <start_airport_code>ORD</start_airport_code>
            <start_gate></start_gate>
            <start_terminal></start_terminal>
            <end_airport_code>PHX</end_airport_code>
            <end_gate></end_gate>
            <end_terminal></end_terminal>
            <marketing_airline>US</marketing_airline>
            <marketing_flight_number>1728</marketing_flight_number>
            <aircraft>A320</aircraft>
            <duration></duration>
            <distance></distance>
            <notes></notes>
            <seats></seats>
            <service_class>Economy</service_class>
            <stops> stops</stops>
        </Segment>
        <Traveler>
            <first_name>William</first_name>
            <middle_name></middle_name>
            <last_name>Never</last_name>
            <frequent_traveler_num></frequent_traveler_num>
            <frequent_traveler_supplier></frequent_traveler_supplier>
            <ticket_num></ticket_num>
        </Traveler>
    </AirObject>
</Response>

POST Itinerary Details

Description

Creates a new trip or updates an existing trip. A new trip will be created if the trip dates span no existing trip and the request doesn't include a tripId. If a tripId is included in the URI it will update the specified trip. The full trip information is included in the update request, which replaces the existing trip.

This endpoint can be used to create trips for a user that is not the OAuth consumer. This is most often done when a travel supplier or Travel Management Company needs to create a trip on behalf of a user. The supplier or TMC must be registered with SAP Concur and have an SAP Concur account that has one of the following user roles: Web Services Administrator for Professional, or Can Administer for Standard.

Agency Proposals

Travel Management Companies for SAP Concur clients with the Agency Proposal feature of Travel Request can send proposed itineraries using the Itinerary web service. The TMC will indicate that the itinerary is a proposal using the TripStatus element. The request must also include the CustomAttributes element and its child elements.

Query Parameters - Required Supported Content Types
None application/xml

Query Parameters - Optional

Examples:
To post a new trip for the OAuth consumer:
https://www.concursolutions.com/api/travel/trip/v1.1

To update a trip for the OAuth consumer:
https://www.concursolutions.com/api/travel/trip/v1.1?tripId={_tripId_}

To post a trip for a user other than the OAuth consumer:
https://www.concursolutions.com/api/travel/trip/v1.1?userid_type=login_id&userid_value={_loginID_}

Request Headers - Required Request Headers - Optional
Authorization header with OAuth token for valid SAP Concur user. To post trips for users other than the OAuth consumer, the OAuth consumer must have one of the following user roles in SAP Concur: Company Administrator or Web Services Administrator for Professional, or Can Administer for Standard. None

Content Body

This function requires as its arguments an Itinerary parent element. The parent element contains the following child elements:

Required Elements

Element Description
TripName Name of the trip. Maximum length: 255 characters.
TripStatus The status of the itinerary. One of the following:
0 - Confirmed
1 - Ticketed
2 - Canceled
6 - Proposal
7 - Booked Proposal

Required Elements for Agency Proposal

Element Description
ClientLocator The unique identifier for the batch of proposals. All proposals in the batch should have the same value.
TravelRequestId The identifier for the travel request that the proposal is associated with.
CustomAttributes This parent element will contain CustomAttributes child element. The CustomAttributes child elements are detailed in the CustomAttributes Elements table.

CustomAttributes Elements - Required

DataType Name Data Supported Values Comment
Numeric ProposalBatchSize 1 to 3 The number of proposals in the batch. Maximum: 3
Numeric ProposalSequenceIndex 1 to 3 The index of the proposal in the batch of proposals.
Text AutoSelectProposal True, False If true, then the proposal will be selected accordingly and replace the segments previously entered by the user.
If False, then the proposal will be up to the user to decide which proposal s/he wants to manually select.
Text TicketIssued True, False Are the tickets for this proposal issued or not.
Text DisplayOnItinerary True The value for this element has to be 'True'.
N/A DisplayTitle N/A This element should be empty.
N/A ExternalId N/A This element should be empty.

Optional Elements

Element Description
BookedByFirstName First name of the trip owner.
BookedByLastName Last name of the trip owner.
Bookings This parent element will contain a Booking child element for each booking associated with this itinerary. The Booking child elements are detailed in the Booking Elements table.
CancelComments User supplied comments if the trip is cancelled. 256 Characters Maximum
Comments Comments on the itinerary. 512 Characters Maximum
DateBookedLocal The date the trip was booked, in the local time of the booking location. Format: YYYY-MM-DDThh:mm:ss
Description The trip description. Maximum length: 512 characters.
IsPersonal Whether the trip is a Business or Leisure trip.
ProjectName The associated project name for the trip. Maximum length: 255 characters.
RuleViolations The list of rule violations associated with the itinerary. This parent element contains a child element for each associated rule violation.

Booking Elements - Required

Element Description
BookingSource The name of the booking source for this booking. A booking source is a textual name the system uses to track where a booking took place. This could be a GDS, OTA, Vendor code for Supplier website, or Supplier Direct Connect API.
RecordLocator The unique identifier for the booking. Send the value for an existing booking to update an existing trip.

Booking Elements - Optional

Element Description
BookingOwner Indicates the tool that supplied the booking to Concur Travel.
Source Obsolete, supported for backward compatibility.
DateBookedLocal The date the booking was created, in the booking location's local time. Format: YYYY-MM-DDThh:mm:ss
FormOfPaymentName The name of the form of payment for the booking.
FormOfPaymentType The type of the form of payment.
TicketMailingAddress The mailing address for the booked ticket, if available.
TicketPickupLocation The pickup location for the booked ticket, if available.
TicketPickupNumber The confirmation number for the booked ticket, if available.
AirfareQuotes List of stored airfare quotes for this booking.
Airline Tickets List of airline tickets for this booking.
Charges List of charges for this booking.
MiscChargeOrders List of Miscellaneous AirCharges for this booking.
Passengers This parent element contains a Passenger child element for each booked passenger. The Passenger child element contains the following child elements:
NameFirst - The first name of the passenger.
NameLast (optional) - The last name of the passenger.
NameMiddle - The middle name of the passenger.
NamePrefix - The passenger's name prefix.
NameRemark - Additional details about the passenger's name.
NameSuffix - The passenger's name suffix.
NameTitle - The passenger's name title.
TextName - The user's full name as entered in the booking tool if different from the name in the database.
FrequentTravelerProgram - Passenger's loyalty programs.
PassPrograms List of Pass Programs for this booking.
PhoneNumbers List of Phone numbers associated with this booking.
RailPayments List of Rail payments associated with rail segments in this booking.
Segments This parent element will contain at least one of the following child elements: Air, Car, Hotel, Dining, Ride, Rail, Parking, Event.
Delivery The method this booking was delivered. 
WaitListSegments The segments that the traveler is waitlisted for this booking.
Warning The warnings associated with the booking.
WebAddresses List of web addresses such as emails, pickup URLs, etc. associated with this booking.
BookingReferrer BookingReferrer is used only in specific source tracking scenarios when there is a need to distinguish between bookings with the same BookingSources coming through different flows. Do not populate without coordinating with your technical contact. The supported values are: Concur Travel, Hipmunk, Sign-in with SAP Concur, Supplier Mobile, Supplier Web

XML Example Request

POST /api/travel/trip/v1.1?userid_type=login_id&userid_value=cm@example.com HTTPS/1.1
Host: www.concursolutions.com
Authorization: OAuth {access token}
Content-Type: application/xml
...

<Itinerary xmlns="http://www.concursolutions.com/api/travel/trip/2010/06">
    <ClientLocator>KK-CNQ-1M1P6-5HJ</ClientLocator>
    <ItinSourceName>ConcurConnectAPI</ItinSourceName>
    <TripName>Trip from Dallas to Seattle</TripName>
    <Comments />
    <StartDateLocal>2013-12-21T07:25:00</StartDateLocal>
    <EndDateLocal>2013-12-24T23:59:00</EndDateLocal>
    <BookedByFirstName>Chris</BookedByFirstName>
    <BookedByLastName>Miller</BookedByLastName>
    <Bookings>
        <Booking>
            <Segments>
                <Car>
                    <Vendor>CQ</Vendor>
                    <Status>HK</Status>
                    <StartDateLocal>2013-12-21T12:00:00</StartDateLocal>
                    <EndDateLocal>2013-12-24T12:00:00</EndDateLocal>
                    <ConfirmationNumber>F1672664579</ConfirmationNumber>
                    <StartCityCode>SEA</StartCityCode>
                    <EndCityCode>SEA</EndCityCode>
                    <StartLocation>SEA</StartLocation>
                    <EndLocation>SEA</EndLocation>
                    <Class>E</Class>
                    <Body>C</Body>
                    <Transmission>M</Transmission>
                    <AirCondition>R</AirCondition>
                    <NumCars>1</NumCars>
                    <DiscountCode>346660</DiscountCode>
                    <DailyRate>44.0000</DailyRate>
                    <TotalRate>44.0000</TotalRate>
                    <RateType>D</RateType>
                    <Currency>USD</Currency>
                    <Charges>
                        <Fixed>
                            <Description>Dropoff Fee</Description>
                            <Currency>USD</Currency>
                            <Amount>0.0000</Amount>
                            <IsPrimary>false</IsPrimary>
                            <SemanticsCode>DROPOFFFEE</SemanticsCode>
                            <SemanticsVendorType>C</SemanticsVendorType>
                        </Fixed>
                        <RateWithAllowance>
                            <Currency>USD</Currency>
                            <Amount>44.0000</Amount>
                            <StartDateLocal>2013-12-21T12:00:00</StartDateLocal>
                            <IsPrimary>true</IsPrimary>
                            <SemanticsCode>DAYS</SemanticsCode>
                            <SemanticsVendorType>C</SemanticsVendorType>
                            <PerUnit>DAY</PerUnit>
                            <NumUnits>1.0000</NumUnits>
                            <AllowanceNumUnits>250.0000</AllowanceNumUnits>
                            <AllowanceAmount>0.2400</AllowanceAmount>
                            <AllowanceIsUnlimited>false</AllowanceIsUnlimited>
                        </RateWithAllowance>
                    </Charges>
                </Car>
            </Segments>
            <Passengers>
                <Passenger>
                    <NameFirst>Chris</NameFirst>
                    <NameLast>Miller</NameLast>
                </Passenger>
            </Passengers>
            <RecordLocator>C123456789</RecordLocator>
            <BookingSource>TravelBookings.com</BookingSource>
            <DateBookedLocal>2013-11-10T13:01:00</DateBookedLocal>
            <ItinSourceName>ConcurConnectAPI</ItinSourceName>
            <PassengerCount>1</PassengerCount>
        </Booking>
        <Booking>
            <Segments>
                <Hotel>
                    <Vendor>CQ</Vendor>
                    <Status>GK</Status>
                    <StartDateLocal>2013-12-21T23:59:00</StartDateLocal>
                    <EndDateLocal>2013-12-24T23:59:00</EndDateLocal>
                    <ConfirmationNumber>3364214265</ConfirmationNumber>
                    <RateCode>LV4</RateCode>
                    <Name>CONCUR HOTEL</Name>
                    <HotelPropertyId>CONQ</HotelPropertyId>
                    <CheckinTime>03:00 PM</CheckinTime>
                    <CheckoutTime>12:00 PM</CheckoutTime>
                    <NumPersons>1</NumPersons>
                    <NumRooms>1</NumRooms>
                    <CancellationPolicy>Cxl 1 day prior to Arrival</CancellationPolicy>
                    <DailyRate>240.3500</DailyRate>
                    <Currency>USD</Currency>
                    <RoomDescription>1 KING BED ACCESSIBLE ROOM - K1RRC</RoomDescription>
                    <Charges>
                        <Rate>
                            <Currency>USD</Currency>
                            <Amount>240.3500</Amount>
                            <StartDateLocal>2013-12-21T23:59:00</StartDateLocal>
                            <IsPrimary>false</IsPrimary>
                            <SemanticsCode>ROOMRATE</SemanticsCode>
                            <SemanticsVendorType>H</SemanticsVendorType>
                            <PerUnit>DAY</PerUnit>
                            <NumUnits>3.0000</NumUnits>
                        </Rate>
                    </Charges>
                </Hotel>
            </Segments>
            <Passengers>
                <Passenger>
                    <NameFirst>Chris</NameFirst>
                    <NameLast>Miller</NameLast>
                </Passenger>
            </Passengers>
            <RecordLocator>0987654321</RecordLocator>
            <BookingSource>TravelBookings.com</BookingSource>
            <DateBookedLocal>2013-11-10T13:01:00</DateBookedLocal>
            <OriginalItinLocator>33491211</OriginalItinLocator>
            <ItinSourceName>ConcurConnectAPI</ItinSourceName>
            <PassengerCount>1</PassengerCount>
        </Booking>
    </Bookings>
</Itinerary>

XML Example Request of Agency Proposal

POST https://www.concursolutions.com/api/travel/trip/v1.1?userid_type=login_id&userid_value=cm@example.com HTTPS/1.1
Authorization: OAuth {access token}
Content-Type: application/xml
...

<Itinerary xmlns="http://www.concursolutions.com/api/travel/trip/2010/06">
    <ClientLocator>KK-CNQ-1M1P6-5HJ</ClientLocator>
    <ItinSourceName>ConcurConnectAPI</ItinSourceName>
    <TripName>Trip from Dallas to Seattle</TripName>
    <Comments />
    <StartDateLocal>2013-12-21T07:25:00</StartDateLocal>
    <EndDateLocal>2013-12-24T23:59:00</EndDateLocal>
    <BookedByFirstName>Chris</BookedByFirstName>
    <BookedByLastName>Miller</BookedByLastName>
    <TripStatus>7</TripStatus>
    <TravelRequestId>3339</TravelRequestId>
    <CustomAttributes>
        <CustomAttribute>
            <ExternalId />
            <DataType>Numeric</DataType>
            <Name>ProposalBatchSize</Name>
            <DisplayTitle />
            <Data>3</Data>
            <DisplayOnItinerary>true</DisplayOnItinerary>
        </CustomAttribute>
        <CustomAttribute>
            <ExternalId />
            <DataType>Numeric</DataType>
            <Name>ProposalSequenceIndex</Name>
            <DisplayTitle />
            <Data>1</Data>
            <DisplayOnItinerary>true</DisplayOnItinerary>
        </CustomAttribute>
    </CustomAttributes>
    <Bookings>
        <Booking>
            <Segments>
                <Car>
                    <Vendor>CQ</Vendor>
                    <Status>HK</Status>
                    <StartDateLocal>2013-12-21T12:00:00</StartDateLocal>
                    <EndDateLocal>2013-12-24T12:00:00</EndDateLocal>
                    <ConfirmationNumber>F1672664579</ConfirmationNumber>
                    <StartCityCode>SEA</StartCityCode>
                    <EndCityCode>SEA</EndCityCode>
                    <StartLocation>SEA</StartLocation>
                    <EndLocation>SEA</EndLocation>
                    <Class>E</Class>
                    <Body>C</Body>
                    <Transmission>M</Transmission>
                    <AirCondition>R</AirCondition>
                    <NumCars>1</NumCars>
                    <DiscountCode>346660</DiscountCode>
                    <DailyRate>44.0000</DailyRate>
                    <TotalRate>44.0000</TotalRate>
                    <RateType>D</RateType>
                    <Currency>USD</Currency>
                    <Charges>
                        <Fixed>
                            <Description>Dropoff Fee</Description>
                            <Currency>USD</Currency>
                            <Amount>0.0000</Amount>
                            <IsPrimary>false</IsPrimary>
                            <SemanticsCode>DROPOFFFEE</SemanticsCode>
                            <SemanticsVendorType>C</SemanticsVendorType>
                        </Fixed>
                        <RateWithAllowance>
                            <Currency>USD</Currency>
                            <Amount>44.0000</Amount>
                            <StartDateLocal>2013-12-21T12:00:00</StartDateLocal>
                            <IsPrimary>true</IsPrimary>
                            <SemanticsCode>DAYS</SemanticsCode>
                            <SemanticsVendorType>C</SemanticsVendorType>
                            <PerUnit>DAY</PerUnit>
                            <NumUnits>1.0000</NumUnits>
                            <AllowanceNumUnits>250.0000</AllowanceNumUnits>
                            <AllowanceAmount>0.2400</AllowanceAmount>
                            <AllowanceIsUnlimited>false</AllowanceIsUnlimited>
                        </RateWithAllowance>
                    </Charges>
                </Car>
            </Segments>
            <Passengers>
                <Passenger>
                    <NameFirst>Chris</NameFirst>
                    <NameLast>Miller</NameLast>
                </Passenger>
            </Passengers>
            <RecordLocator>C123456789</RecordLocator>
            <BookingSource>TravelBookings.com</BookingSource>
            <DateBookedLocal>2013-11-10T13:01:00</DateBookedLocal>
            <ItinSourceName>ConcurConnectAPI</ItinSourceName>
            <PassengerCount>1</PassengerCount>
        </Booking>
        <Booking>
            <Segments>
                <Hotel>
                    <Vendor>CQ</Vendor>
                    <Status>GK</Status>
                    <StartDateLocal>2013-12-21T23:59:00</StartDateLocal>
                    <EndDateLocal>2013-12-24T23:59:00</EndDateLocal>
                    <ConfirmationNumber>3364214265</ConfirmationNumber>
                    <RateCode>LV4</RateCode>
                    <Name>CONCUR HOTEL</Name>
                    <HotelPropertyId>CONQ</HotelPropertyId>
                    <CheckinTime>03:00 PM</CheckinTime>
                    <CheckoutTime>12:00 PM</CheckoutTime>
                    <NumPersons>1</NumPersons>
                    <NumRooms>1</NumRooms>
                    <CancellationPolicy>Cxl 1 day prior to Arrival</CancellationPolicy>
                    <DailyRate>240.3500</DailyRate>
                    <Currency>USD</Currency>
                    <RoomDescription>1 KING BED ACCESSIBLE ROOM - K1RRC</RoomDescription>
                    <Charges>
                        <Rate>
                            <Currency>USD</Currency>
                            <Amount>240.3500</Amount>
                            <StartDateLocal>2013-12-21T23:59:00</StartDateLocal>
                            <IsPrimary>false</IsPrimary>
                            <SemanticsCode>ROOMRATE</SemanticsCode>
                            <SemanticsVendorType>H</SemanticsVendorType>
                            <PerUnit>DAY</PerUnit>
                            <NumUnits>3.0000</NumUnits>
                        </Rate>
                    </Charges>
                </Hotel>
            </Segments>
            <Passengers>
                <Passenger>
                    <NameFirst>Chris</NameFirst>
                    <NameLast>Miller</NameLast>
                </Passenger>
            </Passengers>
            <RecordLocator>0987654321</RecordLocator>
            <BookingSource>TravelBookings.com</BookingSource>
            <DateBookedLocal>2013-11-10T13:01:00</DateBookedLocal>
            <OriginalItinLocator>33491211</OriginalItinLocator>
            <ItinSourceName>ConcurConnectAPI</ItinSourceName>
            <PassengerCount>1</PassengerCount>
        </Booking>
    </Bookings>
</Itinerary>

Post Itinerary Details Response

HTTP Responses Supported Content Types
HTTP Status Codes application/xml

Content Body

When the trip is created successfully, the request will return the full posted trip details with the following additional elements inside the Itinerary parent element:

Element Description
id The URI containing the trip ID.
ItinLocator The Itinerary Locator value (trip ID without the URL). The ItinLocator value is used when updating an existing trip.
DateModifiedUtc The UTC formatted date that this booking was last modified.
BookedVia The GDS the itinerary was booked in.
DateBookedLocal The date, in the traveler's local time, that the booking was made.

Agency Proposal

The response will include the CustomAttributes element and its child elements if the request was an Agency Proposal.

XML Example of Successful Response

<Itinerary xmlns="http://www.concursolutions.com/api/travel/trip/2010/06">
    <id>https://www.concursolutions.com/api/travel/trip/v1.1/CNQR1234567890</id>
    <ItinLocator>CNQR1234567890</ItinLocator>
    <ClientLocator>KK-CNQ-1M1P6-5HJ</ClientLocator>
    <ItinSourceName>ConcurTravel</ItinSourceName>
    <TripName>Trip from Dallas to Seattle</TripName>
    <Comments />
    <StartDateLocal>2013-12-21T07:25:00</StartDateLocal>
    <EndDateLocal>2013-12-24T23:59:00</EndDateLocal>
    <DateModifiedUtc>2012-07-24T19:15:52</DateModifiedUtc>
    <BookedVia>EveryGDS</BookedVia>
    <BookedByFirstName>Chris</BookedByFirstName>
    <BookedByLastName>Miller</BookedByLastName>
    <DateBookedLocal>2012-07-24T19:15:52</DateBookedLocal>
    <Bookings>
        <Booking>
            <Segments>
                <Car>
                    <Vendor>CQ</Vendor>
                    <Status>HK</Status>
                    <StartDateLocal>2013-12-21T12:00:00</StartDateLocal>
                    <EndDateLocal>2013-12-24T12:00:00</EndDateLocal>
                    <ConfirmationNumber>F1672664579</ConfirmationNumber>
                    <DateModifiedUtc>2012-07-24T19:15:52</DateModifiedUtc>
                    <StartCityCode>SEA</StartCityCode>
                    <EndCityCode>SEA</EndCityCode>
                    <StartLocation>SEA</StartLocation>
                    <EndLocation>SEA</EndLocation>
                    <Class>E</Class>
                    <Body>C</Body>
                    <Transmission>M</Transmission>
                    <AirCondition>R</AirCondition>
                    <NumCars>1</NumCars>
                    <DiscountCode>346660</DiscountCode>
                    <DailyRate>44.0000</DailyRate>
                    <TotalRate>44.0000</TotalRate>
                    <RateType>D</RateType>
                    <Currency>USD</Currency>
                    <Charges>
                        <Fixed>
                            <Description>Dropoff Fee</Description>
                            <Currency>USD</Currency>
                            <Amount>0.0000</Amount>
                            <IsPrimary>false</IsPrimary>
                            <SemanticsCode>DROPOFFFEE</SemanticsCode>
                            <SemanticsVendorType>C</SemanticsVendorType>
                        </Fixed>
                        <RateWithAllowance>
                            <Currency>USD</Currency>
                            <Amount>44.0000</Amount>
                            <StartDateLocal>2013-12-21T12:00:00</StartDateLocal>
                            <IsPrimary>true</IsPrimary>
                            <SemanticsCode>DAYS</SemanticsCode>
                            <SemanticsVendorType>C</SemanticsVendorType>
                            <PerUnit>DAY</PerUnit>
                            <NumUnits>1.0000</NumUnits>
                            <AllowanceNumUnits>250.0000</AllowanceNumUnits>
                            <AllowanceAmount>0.2400</AllowanceAmount>
                            <AllowanceIsUnlimited>false</AllowanceIsUnlimited>
                        </RateWithAllowance>
                    </Charges>
                </Car>
            </Segments>
            <Passengers>
                <Passenger>
                    <NameFirst>Chris</NameFirst>
                    <NameLast>Miller</NameLast>
                </Passenger>
            </Passengers>
            <RecordLocator>C123456789</RecordLocator>
            <BookingSource>ConcurCars</BookingSource>
            <DateModifiedUtc>2012-07-24T19:15:52</DateModifiedUtc>
            <DateBookedLocal>2013-11-10T13:01:00</DateBookedLocal>
            <ItinSourceName>TravelSupplier</ItinSourceName>
            <PassengerCount>1</PassengerCount>
        </Booking>
        <Booking>
            <Segments>
                <Hotel>
                    <Vendor>CQ</Vendor>
                    <Status>GK</Status>
                    <StartDateLocal>2013-12-21T23:59:00</StartDateLocal>
                    <EndDateLocal>2013-12-24T23:59:00</EndDateLocal>
                    <ConfirmationNumber>3364214265</ConfirmationNumber>
                    <DateModifiedUtc>2012-07-24T19:15:52</DateModifiedUtc>
                    <RateCode>LV4</RateCode>
                    <Name>CONCUR HOTEL</Name>
                    <HotelPropertyId>CONQ</HotelPropertyId>
                    <CheckinTime>00:00</CheckinTime>
                    <CheckoutTime>00:00</CheckoutTime>
                    <NumPersons>1</NumPersons>
                    <NumRooms>1</NumRooms>
                    <CancellationPolicy>Cxl 1 day prior to Arrival</CancellationPolicy>
                    <DailyRate>240.3500</DailyRate>
                    <Currency>USD</Currency>
                    <RoomDescription>1 KING BED ACCESSIBLE ROOM - K1RRC</RoomDescription>
                    <Charges>
                        <Rate>
                            <Currency>USD</Currency>
                            <Amount>240.3500</Amount>
                            <StartDateLocal>2013-12-21T23:59:00</StartDateLocal>
                            <IsPrimary>false</IsPrimary>
                            <SemanticsCode>ROOMRATE</SemanticsCode>
                            <SemanticsVendorType>H</SemanticsVendorType>
                            <PerUnit>DAY</PerUnit>
                            <NumUnits>3.0000</NumUnits>
                        </Rate>
                    </Charges>
                </Hotel>
            </Segments>
            <Passengers>
                <Passenger>
                    <NameFirst>Chris</NameFirst>
                    <NameLast>Miller</NameLast>
                </Passenger>
            </Passengers>
            <RecordLocator>0987654321</RecordLocator>
            <BookingSource>ConcurHotel</BookingSource>
            <DateModifiedUtc>2012-07-24T19:15:52</DateModifiedUtc>
            <DateBookedLocal>2013-11-10T13:01:00</DateBookedLocal>
            <OriginalItinLocator>33491211</OriginalItinLocator>
            <ItinSourceName>ConcurTravel</ItinSourceName>
            <PassengerCount>1</PassengerCount>
        </Booking>
    </Bookings>
</Itinerary>

XML Example of Successful Response for Agency Proposal

<Itinerary xmlns="http://www.concursolutions.com/api/travel/trip/2010/06">
    <id>https://www.concursolutions.com/api/travel/trip/v1.1/CNQR1234567890</id>
    <ItinLocator>CNQR1234567890</ItinLocator>
    <ClientLocator>KK-CNQ-1M1P6-5HJ</ClientLocator>
    <ItinSourceName>ConcurTravel</ItinSourceName>
    <TripName>Trip from Dallas to Seattle</TripName>
    <Comments />
    <StartDateLocal>2013-12-21T07:25:00</StartDateLocal>
    <EndDateLocal>2013-12-24T23:59:00</EndDateLocal>
    <DateModifiedUtc>2012-07-24T19:15:52</DateModifiedUtc>
    <BookedVia>EveryGDS</BookedVia>
    <BookedByFirstName>Chris</BookedByFirstName>
    <BookedByLastName>Miller</BookedByLastName>
    <DateBookedLocal>2012-07-24T19:15:52</DateBookedLocal>
    <Bookings>
        <Booking>
            <Segments>
                <Car>
                    <Vendor>CQ</Vendor>
                    <Status>HK</Status>
                    <StartDateLocal>2013-12-21T12:00:00</StartDateLocal>
                    <EndDateLocal>2013-12-24T12:00:00</EndDateLocal>
                    <ConfirmationNumber>F1672664579</ConfirmationNumber>
                    <DateModifiedUtc>2012-07-24T19:15:52</DateModifiedUtc>
                    <StartCityCode>SEA</StartCityCode>
                    <EndCityCode>SEA</EndCityCode>
                    <StartLocation>SEA</StartLocation>
                    <EndLocation>SEA</EndLocation>
                    <Class>E</Class>
                    <Body>C</Body>
                    <Transmission>M</Transmission>
                    <AirCondition>R</AirCondition>
                    <NumCars>1</NumCars>
                    <DiscountCode>346660</DiscountCode>
                    <DailyRate>44.0000</DailyRate>
                    <TotalRate>44.0000</TotalRate>
                    <RateType>D</RateType>
                    <Currency>USD</Currency>
                    <Charges>
                        <Fixed>
                            <Description>Dropoff Fee</Description>
                            <Currency>USD</Currency>
                            <Amount>0.0000</Amount>
                            <IsPrimary>false</IsPrimary>
                            <SemanticsCode>DROPOFFFEE</SemanticsCode>
                            <SemanticsVendorType>C</SemanticsVendorType>
                        </Fixed>
                        <RateWithAllowance>
                            <Currency>USD</Currency>
                            <Amount>44.0000</Amount>
                            <StartDateLocal>2013-12-21T12:00:00</StartDateLocal>
                            <IsPrimary>true</IsPrimary>
                            <SemanticsCode>DAYS</SemanticsCode>
                            <SemanticsVendorType>C</SemanticsVendorType>
                            <PerUnit>DAY</PerUnit>
                            <NumUnits>1.0000</NumUnits>
                            <AllowanceNumUnits>250.0000</AllowanceNumUnits>
                            <AllowanceAmount>0.2400</AllowanceAmount>
                            <AllowanceIsUnlimited>false</AllowanceIsUnlimited>
                        </RateWithAllowance>
                    </Charges>
                </Car>
            </Segments>
            <Passengers>
                <Passenger>
                    <NameFirst>Chris</NameFirst>
                    <NameLast>Miller</NameLast>
                </Passenger>
            </Passengers>
            <RecordLocator>C123456789</RecordLocator>
            <BookingSource>ConcurCars</BookingSource>
            <DateModifiedUtc>2012-07-24T19:15:52</DateModifiedUtc>
            <DateBookedLocal>2013-11-10T13:01:00</DateBookedLocal>
            <ItinSourceName>TravelSupplier</ItinSourceName>
            <PassengerCount>1</PassengerCount>
        </Booking>
        <Booking>
            <Segments>
                <Hotel>
                    <Vendor>CQ</Vendor>
                    <Status>GK</Status>
                    <StartDateLocal>2013-12-21T23:59:00</StartDateLocal>
                    <EndDateLocal>2013-12-24T23:59:00</EndDateLocal>
                    <ConfirmationNumber>3364214265</ConfirmationNumber>
                    <DateModifiedUtc>2012-07-24T19:15:52</DateModifiedUtc>
                    <RateCode>LV4</RateCode>
                    <Name>CONCUR HOTEL</Name>
                    <HotelPropertyId>CONQ</HotelPropertyId>
                    <CheckinTime>00:00</CheckinTime>
                    <CheckoutTime>00:00</CheckoutTime>
                    <NumPersons>1</NumPersons>
                    <NumRooms>1</NumRooms>
                    <CancellationPolicy>Cxl 1 day prior to Arrival</CancellationPolicy>
                    <DailyRate>240.3500</DailyRate>
                    <Currency>USD</Currency>
                    <RoomDescription>1 KING BED ACCESSIBLE ROOM - K1RRC</RoomDescription>
                    <Charges>
                        <Rate>
                            <Currency>USD</Currency>
                            <Amount>240.3500</Amount>
                            <StartDateLocal>2013-12-21T23:59:00</StartDateLocal>
                            <IsPrimary>false</IsPrimary>
                            <SemanticsCode>ROOMRATE</SemanticsCode>
                            <SemanticsVendorType>H</SemanticsVendorType>
                            <PerUnit>DAY</PerUnit>
                            <NumUnits>3.0000</NumUnits>
                        </Rate>
                    </Charges>
                </Hotel>
            </Segments>
            <Passengers>
                <Passenger>
                    <NameFirst>Chris</NameFirst>
                    <NameLast>Miller</NameLast>
                </Passenger>
            </Passengers>
            <RecordLocator>0987654321</RecordLocator>
            <BookingSource>ConcurHotel</BookingSource>
            <DateModifiedUtc>2012-07-24T19:15:52</DateModifiedUtc>
            <DateBookedLocal>2013-11-10T13:01:00</DateBookedLocal>
            <OriginalItinLocator>33491211</OriginalItinLocator>
            <ItinSourceName>ConcurTravel</ItinSourceName>
            <PassengerCount>1</PassengerCount>
        </Booking>
    </Bookings>
    <CustomAttributes>
        <CustomAttribute>
            <ExternalId />
            <DataType>Numeric</DataType>
            <Name>ProposalBatchSize</Name>
            <DisplayTitle />
            <Data>3</Data>
            <DisplayOnItinerary>true</DisplayOnItinerary>
        </CustomAttribute>
        <CustomAttribute>
            <ExternalId />
            <DataType>Numeric</DataType>
            <Name>ProposalSequenceIndex</Name>
            <DisplayTitle />
            <Data>1</Data>
            <DisplayOnItinerary>true</DisplayOnItinerary>
        </CustomAttribute>
    </CustomAttributes>
</Itinerary>

Post Itinerary Cancellation Request

Description Supported Content Types
Cancels all segments in the supplied trip.
This endpoint can be used to cancel trips for a user that is not the OAuth consumer. This is most often done when a travel supplier or Travel Management Company needs to cancel a trip on behalf of a user. The supplier or TMC must be registered with SAP Concur and have an SAP Concur account with one of the following user roles: Web Services Administrator for Professional, or Can Administer for Standard.
application/xml

Query Parameters - Required

Example:
https://www.concursolutions.com/api/travel/trip/v1.1/cancel?tripId={_tripId_}

Query Parameters - Optional

Example:
https://www.concursolutions.com/api/travel/trip/v1.1/cancel?tripId={_tripId_}&userid_type=login_id&userid_value={_loginID_}

Request Headers - Required Request Headers - Optional
Authorization header with OAuth token for a valid SAP Concur user. The OAuth consumer must have one of the following user roles in SAP Concur: Company Administrator or Web Services Administrator for Professional, or Can Administer for Standard. None

XML Example Request

POST /api/travel/trip/v1.1/cancel?tripId=CNQR1234567890 HTTPS/1.1
Host: www.concursolutions.com
Authorization: OAuth {access token}
...

POST Itinerary Cancellation

HTTP Responses Supported Content Types
HTTP Status Codes application/xml

Content Body

The request will return the full trip details for the cancelled trip. The trip will contain no segments, as those are all cancelled. The response includes the following additional elements inside the Itinerary parent element:

Element Description
id The URI containing the trip ID.
ItinLocator The Itinerary Locator value (trip ID without the URL).
ClientLocator The identifier for the client.
DateModifiedUtc The UTC formatted date that this booking was last modified.
BookedVia The GDS the itinerary was booked in.
DateBookedLocal The date, in the traveler's local time, that the booking was made.

XML Example of Successful Response

<Itinerary xmlns="http://www.concursolutions.com/api/travel/trip/2010/06">
    <id>https://www.concursolutions.com/api/travel/trip/v1.1/CNQR1234567890</id>
    <ItinLocator>CNQR1234567890</ItinLocator>
    <ClientLocator>KK-CNQ-1M1P6-5HJ</ClientLocator>
    <ItinSourceName>ConcurTravel</ItinSourceName>
    <TripName>Trip from Dallas to Seattle</TripName>
    <Comments />
    <StartDateLocal>2013-12-21T07:25:00</StartDateLocal>
    <EndDateLocal>2013-12-24T23:59:00</EndDateLocal>
    <DateModifiedUtc>2012-07-24T19:15:52</DateModifiedUtc>
    <BookedVia>EveryGDS</BookedVia>
    <BookedByFirstName>Chris</BookedByFirstName>
    <BookedByLastName>Miller</BookedByLastName>
    <DateBookedLocal>2012-07-24T19:15:52</DateBookedLocal>
    <Bookings>
        <Booking>
            <Segments/>
            <Passengers>
                <Passenger>
                    <NameFirst>Chris</NameFirst>
                    <NameLast>Miller</NameLast>
                </Passenger>
            </Passengers>
            <RecordLocator>C123456789</RecordLocator>
            <BookingSource>ConcurCars</BookingSource>
            <DateModifiedUtc>2012-07-24T19:15:52</DateModifiedUtc>
            <DateBookedLocal>2013-11-10T13:01:00</DateBookedLocal>
            <ItinSourceName>TravelSupplier</ItinSourceName>
            <PassengerCount>1</PassengerCount>
        </Booking>
        <Booking>
            <Segments/>
            <Passengers>
                <Passenger>
                    <NameFirst>Chris</NameFirst>
                    <NameLast>Miller</NameLast>
                </Passenger>
            </Passengers>
            <RecordLocator>0987654321</RecordLocator>
            <BookingSource>ConcurHotel</BookingSource>
            <DateModifiedUtc>2012-07-24T19:15:52</DateModifiedUtc>
            <DateBookedLocal>2013-11-10T13:01:00</DateBookedLocal>
            <OriginalItinLocator>33491211</OriginalItinLocator>
            <ItinSourceName>ConcurTravel</ItinSourceName>
            <PassengerCount>1</PassengerCount>
        </Booking>
    </Bookings>
</Itinerary>

POST Booking Details

Creates a new booking or updates an existing booking. A new booking will be assigned to the specified trip, or if no trip is specified, the first itinerary that spans the booking dates. If no trip is specified and no itinerary exists that spans the booking dates, a new itinerary will be created.

This endpoint can be used to create/update bookings for a user that is not the OAuth consumer. This is most often done when a travel supplier or Travel Management Company needs to create/update a booking on behalf of a user. The supplier or TMC must be registered with SAP Concur, and must have an account that has one of the following user roles: Web Services Administrator for Professional, or Can Administer for Standard.

POST /api/travel/booking/v1.0?tripId=12345678 HTTPS/1.1
Host: www.concursolutions.com
Authorization: OAuth {access token}

Request Parameters

Query Parameters - Optional

Examples:

https://www.concursolutions.com/api/travel/booking/v1.1?tripId={tripId}

https://www.concursolutions.com/api/travel/booking/v1.1?userid_type=login_id&userid_value={loginID}

Request Body Root Elements

The request contains a Booking parent element with the following child elements:

Required Element Description
BookingSource The supplier's name.
ItinSourceName The itinerary source. Format: TravelSupplier
RecordLocator Record locator for this booking. This is often six alphanumeric characters but can have other formats depending on the booking source
Optional Element Description
DateBookedLocal The date the booking was created, in the booking location's local time. Format: YYYY-MM-DDThh:mm:ss
FormOfPaymentName The name of the form of payment for the booking.
FormOfPaymentType The type of the form of payment.
TicketMailingAddress The mailing address for the booked ticket, if available.
TicketPickupLocation The pickup location for the booked ticket, if available
TicketPickupNumber The confirmation number to pick up the booked ticket, if available.
AirfareQuotes List of stored airfare quotes for this booking.
AirlineTickets List of Airline Tickets for this booking.
Charges List of Charges for this booking.
MiscChargeOrders List of Miscellaneous AirCharges for this booking.
Passengers The Passengers element contains child element for each booked passenger. The description of each child element can be seen in a subsequent table.
PassPrograms List of Pass Programs for this booking.
PhoneNumbers List of Phone numbers associated with this booking.
RailPayments List of Rail payments associated with rail segments in this booking.
Segments List of Segments in this booking. This parent element contains one or more Air, Car, Hotel, Dining, Ride, Rail, Parking, or Event parent elements for the booking.
Delivery The method this booking was delivered. 
WaitListSegments The segments that the traveler is waitlisted for this booking.
Warnings The warnings associated with the booking.
WebAddresses List of web addresses such as emails, pickup URLs, etc. associated with this booking
BookingReferrer BookingReferrer is used only in specific source tracking scenarios when there is a need to distinguish between bookings with the same BookingSources coming through different flows. Do not populate without coordinating with your technical contact. The supported values are: Concur Travel, Hipmunk, Sign-in with SAP Concur, Supplier Mobile, Supplier Web

Passenger Child Elements

Required Element Description
NameFirst The first name of the passenger.
NameLast The last name of the passenger.
Optional Element Description
NameMiddle The middle name of the passenger.
NamePrefix The name prefix of the passenger.
NameRemark Additional details about the passenger's name.
NameSuffix The name suffix of the passenger.
NameTitle The title of the passenger.
TextName The user's full name as entered in the booking tool if different from the name in the database.
FrequentTravelerProgram Passenger's loyalty programs

Response

This function returns the full trip details.

If the end user updates an existing reservation which results in a new confirmation number, the old booking must be explicitly cancelled in addition to posting the new booking to SAP Concur. If the previous booking is not cancelled, the user will see both bookings in their SAP Concur trip list.

Examples

Example 1: XML Example Request

POST /api/travel/booking/v1.0?tripId=12345678 HTTPS/1.1
Host: www.concursolutions.com
Authorization: OAuth {access token}
Content-Type: application/xml
...

<Booking xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <Segments>
        <Car>
            <Vendor>AL</Vendor>
            <VendorName>Alamo</VendorName>
            <Status>HK</Status>
            <StartDateLocal>2013-12-21T12:00:00</StartDateLocal>
            <EndDateLocal>2013-12-23T12:00:00</EndDateLocal>
            <StartDateUtc>2013-12-21T20:00:00</StartDateUtc>
            <EndDateUtc>2013-12-23T20:00:00</EndDateUtc>
            <ConfirmationNumber>F16726AIUS</ConfirmationNumber>
            <DateCreatedUtc>2012-07-22T11:55:42</DateCreatedUtc>
            <DateModifiedUtc>2012-07-22T11:55:42</DateModifiedUtc>
            <StartCityCode>SEA</StartCityCode>
            <EndCityCode>SEA</EndCityCode>
            <StartLocation>SEA</StartLocation>
            <EndLocation>SEA</EndLocation>
            <Class>E</Class>
            <Body>C</Body>
            <Transmission>A</Transmission>
            <AirCondition>R</AirCondition>
            <NumPersons>1</NumPersons>
            <NumCars>1</NumCars>
            <DiscountCode>4321</DiscountCode>
            <DailyRate>35.0000</DailyRate>
            <TotalRate>105.0000</TotalRate>
            <RateType>D</RateType>
            <Currency>USD</Currency>
        </Car>
    </Segments>
    <RecordLocator>PANAMA50</RecordLocator>
    <BookingSource>Alamo</BookingSource>
    <DateCreatedUtc>2012-07-22T11:55:42</DateCreatedUtc>
    <DateModifiedUtc>2012-07-22T11:55:42</DateModifiedUtc>
    <DateBookedLocal>2013-11-10T13:01:00</DateBookedLocal>
    <ItinSourceName>TravelSupplier</ItinSourceName>
    <Passengers>
        <Passenger>
            <PassengerKey>0</PassengerKey>
            <NameFirst>Chris</NameFirst>
            <NameLast>Miller</NameLast>
        </Passenger>
    </Passengers>
</Booking>

Example 2: XML Example of Successful Response

<Itinerary xmlns="https://www.concursolutions.com/api/travel/trip/2010/06">
    <id>https://www.concursolutions.com/api/travel/trip/v1.1/CNQR1234567890</id>
    <ItinLocator>CNQR1234567890</ItinLocator>
    <ClientLocator>KK-CNQ-1M1P6-5HJ</ClientLocator>
    <ItinSourceName>TravelSupplier</ItinSourceName>
    <TripName>Trip to Seattle</TripName>
    <Comments />
    <StartDateLocal>2013-12-21T07:25:00</StartDateLocal>
    <EndDateLocal>2013-12-23T23:59:00</EndDateLocal>
    <DateModifiedUtc>2012-07-24T19:15:52</DateModifiedUtc>
    <BookedVia>EveryGDS</BookedVia>
    <BookedByFirstName>Chris</BookedByFirstName>
    <BookedByLastName>Miller</BookedByLastName>
    <DateBookedLocal>2012-07-24T19:15:52</DateBookedLocal>
    <Booking>
        <Segments>
            <Car>
                <Vendor>AL</Vendor>
                <VendorName>Alamo</VendorName>
                <Status>HK</Status>
                <StartDateLocal>2013-12-21T12:00:00</StartDateLocal>
                <EndDateLocal>2013-12-23T12:00:00</EndDateLocal>
                <StartDateUtc>2013-12-21T20:00:00</StartDateUtc>
                <EndDateUtc>2013-12-23T20:00:00</EndDateUtc>
                <ConfirmationNumber>F16726AIUS</ConfirmationNumber>
                <DateCreatedUtc>2012-07-22T11:55:42</DateCreatedUtc>
                <DateModifiedUtc>2012-07-22T11:55:42</DateModifiedUtc>
                <StartCityCode>SEA</StartCityCode>
                <EndCityCode>SEA</EndCityCode>
                <StartLocation>SEA</StartLocation>
                <EndLocation>SEA</EndLocation>
                <Class>E</Class>
                <Body>C</Body>
                <Transmission>A</Transmission>
                <AirCondition>R</AirCondition>
                <NumPersons>1</NumPersons>
                <NumCars>1</NumCars>
                <DiscountCode>4321</DiscountCode>
                <DailyRate>35.0000</DailyRate>
                <TotalRate>105.0000</TotalRate>
                <RateType>D</RateType>
                <Currency>USD</Currency>
            </Car>
        </Segments>
        <RecordLocator>PANAMA50</RecordLocator>
        <BookingSource>Alamo</BookingSource>
        <DateCreatedUtc>2012-07-22T11:55:42</DateCreatedUtc>
        <DateModifiedUtc>2012-07-22T11:55:42</DateModifiedUtc>
        <DateBookedLocal>2013-11-10T13:01:00</DateBookedLocal>
        <ItinSourceName>TravelSupplier</ItinSourceName>
        <Passengers>
            <Passenger>
                <PassengerKey>0</PassengerKey>
                <NameFirst>Chris</NameFirst>
                <NameLast>Miller</NameLast>
            </Passenger>
        </Passengers>
    </Booking>
</Itinerary>

POST Booking Cancellation

Cancels an existing booking. By default, the OAuth consumer should be the owner of the booking. This endpoint can also be used to cancel bookings that the OAuth consumer does not own. This is most often done when a Travel Management Company needs to cancel bookings on behalf of a user. The TMC must be registered with SAP Concur and have an SAP Concur account that has one of the following user roles: Web Services Administrator for Professional, or Can Administer for Standard.

NOTE:
Booking records can only be updated by the booking source that created them. SAP Concur verifies the source information before processing the request.

POST /api/travel/booking/v1.1/cancel?bookingSource={FastTravel}&confirmationNumber={098765431} HTTPS/1.1
Host: www.concursolutions.com
Authorization: OAuth {access token}

Request Parameters

Query Parameters - Required

The cancel keyword and the unique identifier for the supplier, configured by SAP Concur during the application review. The bookingSource must match the Supplier Name associated with the booking.

The confirmation number for the booking to cancel.

Example: https://www.concursolutions.com/api/travel/booking/v1.1/cancel?bookingSource={Supplier}&confirmationNumber={confnum}

Query Parameters - Optional

The SAP Concur login ID of the user who owns the booking. Only provided when the booking owner is not the OAuth consumer. Can only be used when the OAuth consumer has the required user role.

Example: https://www.concursolutions.com/api/travel/booking/v1.1/cancel?bookingSource={Supplier}&confirmationNumber={confnum}&userid_type=login_id&userid_value={loginID}

Content Type

application/xml

Authorization Header

The authorization header must have an OAuth token for a valid SAP Concur user. The OAuth consumer must be registered as a Supplier or TMC with SAP Concur, and must have one of the following user roles in SAP Concur: Company Administrator or Web Services Administrator for Professional, or Can Administer for Standard.

Response

This function returns the full booking details. If the booking is not found, the function returns a HTTP 404 error and the following element:

Status: This element contains the value: NotFound.

Examples

Examples 1: XML Example Request

POST /api/travel/booking/v1.1/cancel?bookingSource={FastTravel}&confirmationNumber={098765431} HTTPS/1.1
Host: www.concursolutions.com
Authorization: OAuth {access token}

Examples 2: XML Example of Successful Response

<Car>
    <Vendor>ZE</Vendor>
    <Status>HK</Status>
    <StartDateLocal>2013-12-21T12:00:00</StartDateLocal>
    <EndDateLocal>2013-12-24T12:00:00</EndDateLocal>
    <TimeZoneId xsi:nil="true"/>
    <StartDateUtc>2013-12-21T20:00:00</StartDateUtc>
    <EndDateUtc>2013-12-24T20:00:00</EndDateUtc>
    <ConfirmationNumber>0987654321</ConfirmationNumber>
    <CancellationNumber>1029384756</CancellationNumber>
    <DateCreatedUtc>2012-07-22T11:55:42</DateCreatedUtc>
    <DateCancelledUtc>2012-07-25T14:21:35</DateCancelledUtc>
    <DateModifiedUtc>2012-07-22T11:55:42</DateModifiedUtc>
    <UpgradedDateTime xsi:nil="true"/>
    <IsUpgradeAllowed xsi:nil="true"/>
    <FrequentTravelerId/>
    <StartCityCode>SEA</StartCityCode>
    <EndCityCode>SEA</EndCityCode>
    <StartLocation>SEA</StartLocation>
    <EndLocation>SEA</EndLocation>
    <Class>E</Class>
    <Body>C</Body>
    <Transmission>M</Transmission>
    <AirCondition>R</AirCondition>
    <PhoneNumber/>
    <NumPersons xsi:nil="true"/>
    <NumCars>1</NumCars>
    <DiscountCode>346660</DiscountCode>
    <Charges>
        <Fixed>
            <Description>Dropoff Fee</Description>
            <Currency>USD</Currency>
            <Amount>0.0000</Amount>
            <StartDateLocal xsi:nil="true"/>
            <IsPaid xsi:nil="true"/>
            <SemanticsCode>DROPOFFFEE</SemanticsCode>
            <SemanticsVendorType>C</SemanticsVendorType>
        </Fixed>
        <RateWithAllowance>
            <Currency>USD</Currency>
            <Amount>44.0000</Amount>
            <StartDateLocal>2013-12-21T12:00:00</StartDateLocal>
            <IsPaid xsi:nil="true"/>
            <SemanticsCode>DAYS</SemanticsCode>
            <SemanticsVendorType>C</SemanticsVendorType>
            <PerUnit>DAY</PerUnit>
            <NumUnits>1.0000</NumUnits>
            <AllowanceUnit/>
            <AllowanceNumUnits>250.0000</AllowanceNumUnits>
            <AllowanceAmount>0.2400</AllowanceAmount>
            <AllowanceIsUnlimited>false</AllowanceIsUnlimited>
        </RateWithAllowance>
    </Charges>
    <Remarks/>
    <PerDiemLocation/>
</Car>

Booking Object Elements

The booking elements contain many child elements. For ease of use, these elements are divided into the Core Elements, which are the most frequently used, and Additional Elements, which are not often used but are supported by the Itinerary web service. Some elements only appear if the travel supplier created the booking. Elements are marked as required if they must be supplied for a new booking.

NOTE: TripLink - Open Booking suppliers see a targeted subset of these fields. Refer to the documentation here for the TripLink - Open Booking supplier booking object elements.

Air Booking Elements

Core Elements - Required

Element Description
ClassOfService The class of the booking.
ConfirmationNumber The record locator or confirmation number for the flight from the airline.
EndCityCode The IATA airport code for the end city of the booking.
EndDateLocal The booking ending time and date, in the booking location's local time. Format: YYYY-MM-DDThh:mm:ss
FlightNumber The flight number for the booking.
StartCityCode The IATA airport code for the starting address for the booking.
StartDateLocal The booking starting time and date, in the booking location's local time. Format: YYYY-MM-DDThh:mm:ss
Vendor The two letter GDS vendor code. Use $$ when not available.

Core Elements - Optional

Element Description
CancellationNumber The cancellation number from the vendor. This field should be set when you cancel a segment.
CancellationPolicy The cancellation policy from the vendor.
Charges The charges for this booking. Refer to the Charges Child Elements table.
DateCancelledUtc The date the booking was cancelled, in UTC. Format: YYYY-MM-DDThh:mm:ss
DateCreatedUtc The date the booking was created, in UTC. Format: YYYY-MM-DDThh:mm:ss
DateModifiedUtc The date the booking was modified, in UTC. Format: YYYY-MM-DDThh:mm:ss
EndDateUtc The booking ending time and date, in UTC. Format: YYYY-MM-DDThh:mm:ss
EndGate The arrival gate for the booking.
EndTerminal The arrival terminal for the booking.
LegId The leg ID of the booking. Leg IDs do not change on a connection. For each unique leg ID in the trip, all flights subsequent to the first segment with the same leg ID are connections.
Seats The seats for the booking. This parent element contains an AirSeat element for each included seat. The AirSeat element contains the following child elements: PassengerRph - The passenger assigned to the seat. SeatNumber - The number of the seat.
StartDateUtc The booking starting time and date, in UTC. Format: YYYY-MM-DDThh:mm:ss
StartGate The departure gate for the booking.
StartTerminal The departure terminal for the booking.
Status The GDS based booking status for the segment such as HK, HL, BK, etc.
TimeZone The time zone of the booking. Format: One of the supported Olson or Windows Time Zones.

Additional Elements - Optional

Element Description
AircraftCode The code for the aircraft type.
Bags The number of bags included in the booking.
Cabin The section of the airplane for the booking.
CarbonEmissionLbs The pounds of carbon emission for this booking.
CarbonModel The model used to calculate the carbon emissions.
CheckedBaggage Whether the booking includes checked baggage.
Duration The duration of the booked flight.
ETicket Whether the booking has an e-ticket. Format: Y/N
IsOpenSegment Whether the segment is open. Format: True/False
IsPreferredVendor If the airline is marked as a preferred property by the company. Format: True/False
IsUpgradeAllowed Whether the booking can be upgraded. Format: True/False
Meals The meals included in the booking.
Miles The number of miles included in the booking.
Notes Additional details about the booking.
OpenSegment Additional information about the open segment.
OperatedByFlightNumber Flight Number provided by the airline operating the flight on behalf of the booked airline.
OperatedByVendor The airline operating the flight on behalf of the booked airline.
OperatedByVendorName The name of the airline operating the flight on behalf of the booked airline.
Services The services included in the booking.
SpecialInstructions Additional instructions regarding the booking. Max Length: 256
UpgradedDateTime The date and time the booking was upgraded. Format: YYYY-MM-DDThh:mm:ss

Car Booking Elements

Core Elements - Required

Element Description
ConfirmationNumber The confirmation number from the vendor.
EndDateLocal The booking ending time and date, in the booking location's local time. Format: YYYY-MM-DDThh:mm:ss
StartDateLocal The booking starting time and date, in the booking location's local time. Format: YYYY-MM-DDThh:mm:ss
Vendor The two letter GDS vendor code.

Core Elements - Optional

Element Description
CancellationNumber The cancellation number from the vendor. This field should be set when you cancel a segment.
CancellationPolicy The cancellation policy from the vendor.
Charges The charges for this booking. Refer to the Charges Child Elements table.
Currency The 3-letter ISO 4217 currency code for the booking.
DailyRate The daily rate for the booking.
DateCancelledUtc The date the booking was cancelled, in UTC. Format: YYYY-MM-DDThh:mm:ss
DateCreatedUtc The date the booking was created, in UTC. Format: YYYY-MM-DDThh:mm:ss
DateModifiedUtc The date the booking was modified, in UTC. Format: YYYY-MM-DDThh:mm:ss
EndCityCode The IATA airport code for the ending address for the booking.
EndDateUtc The booking ending time and date, in UTC. Format: YYYY-MM-DDThh:mm:ss
EndLatitude The latitude for the ending location of the booking.
EndLongitude The longitude for the ending location of the booking.
Notes Additional information about the booking.
PhoneNumber The phone number for the user.
RateCode The rate code for the booking.
StartCityCode The IATA airport code for the starting address for the booking.
StartDateUtc The booking starting time and date, in UTC. Format: YYYY-MM-DDThh:mm:ss
StartLatitude The latitude for the starting location of the booking.
StartLongitude The longitude for the starting location of the booking.
Status The booking status.
TimeZone The time zone of the booking. Format: One of the supported Olson or Windows Time Zones.
TotalRate The total rate amount of the booking.
VendorName The name of the vendor. When using the Unknown Vendor Code ($$), this value appears as the vendor in the itinerary.

Additional Elements - Optional

Element Description
AirCondition The character code that indicates if car has an air conditioner. R for AC, N for No AC
Body The character code to indicate how many passengers the car can seat.
Class Character code to indicate the class of the car e.g. if it is economy, full size, compact, etc. Varies by Vendor
DiscountCode The discount code used by the company/TMC to get a discounted rate.
DropoffCollectionAddress1 The AddressLine1 for the dropoff address when the rental service offers dropoff.
DropoffCollectionAddressType  
DropoffCollectionCategory  
DropoffCollectionCity City for the dropoff address when the rental service offers dropoff.
DropoffCollectionCityCode The IATA airport code for the dropoff address when the rental service offers dropoff.
DropoffCollectionCountry The country for the dropoff address when the rental service offers dropoff.
DropoffCollectionLatitude The latitude for the dropoff address when the rental service offers dropoff.
DropoffCollectionLongitude The longitude for the dropoff address when the rental service offers dropoff.
DropoffCollectionNumber  
DropoffCollectionPhoneNumber The phone number for the dropoff address when the rental service offers dropoff.
DropoffCollectionPostalCode The postal code for the dropoff address when the rental service offers dropoff.
DropoffCollectionState The state for the dropoff address when the rental service offers dropoff.
EndAddress The ending address for the booking.
EndAddress2 The ending address for the booking.
EndCity The ending address for the booking.
EndCloseTime The closing time for the dropoff location.
EndCountry The ending address for the booking.
EndLocation The dropoff location.
EndOpenTime The opening time of the dropoff location.
EndPhoneNumber The phone number of the dropoff location.
EndPostalCode The ending address for the booking.
EndState The ending address for the booking.
FrequentTravelerId The loyalty program ID for the user.
IsUpgradeAllowed Whether the booking can be upgraded. Format: True/False
NumCars The number of cars rented.
NumPersons The number of people including the driver that the rental is for.
PickupDeliveryAddress1 The AddressLine1 for the pickup address when the rental service offers pickup.
PickupDeliveryAddressType  
PickupDeliveryCategory  
PickupDeliveryCity The city for the pickup address when the rental service offers pickup.
PickupDeliveryCityCode The IATA airport code for the pickup address when the rental service offers pickup.
PickupDeliveryCountry The country for the pickup address when the rental service offers pickup.
PickupDeliveryLatitude The latitude for the pickup address when the rental service offers pickup.
PickupDeliveryLongitude The longitude for the pickup address when the rental service offers pickup.
PickupDeliveryNumber  
PickupDeliveryPhoneNumber The phone number for the pickup address when the rental service offers pickup.
PickupDeliveryPostalCode The postal code for the pickup address when the rental service offers pickup.
PickupDeliveryState The state for the pickup address when the rental service offers pickup.
RateType The rate type for the booking.
SpecialEquipment Any special equipment required by the renter.
SpecialInstructions Additional instructions regarding the booking. Max Length: 256
StartAddress The starting address of the booking.
StartAddress2 The starting address for the booking.
StartCity The starting address for the booking.
StartCloseTime The closing time for the pickup location.
StartCountry The starting address for the booking.
StartLocation The starting location of the booking.
StartOpenTime The opening time for the pickup location.
StartPostalCode The starting address for the booking.
StartState The starting address for the booking.
Transmission The character code that indicates if the car has auto-transmission. A for Auto, M for Manual
UpgradedDateTime The date and time the booking was upgraded. Format: YYYY-MM-DDThh:mm:ss

Hotel Booking Elements

Core Elements - Required

Element Description
ConfirmationNumber The confirmation number from the vendor.
EndDateLocal The booking ending time and date, in the booking location's local time. Format: YYYY-MM-DDThh:mm:ss
Name The hotel name for the booking.
StartCityCode The IATA airport code for the starting address for the booking.
StartDateLocal The booking starting time and date, in the booking location's local time. Format: YYYY-MM-DDThh:mm:ss
Status The booking status.
Vendor The two letter GDS vendor code.

Core Elements - Optional

Element Description
CancellationNumber The cancellation number from the vendor. This field should be set when you cancel a segment.
CancellationPolicy The cancellation policy from the vendor.
Charges The charges for this booking. Refer to the Charges Child Elements table.
CheckinTime The check in time for the hotel booking.
CheckoutTime The check out time for the hotel booking.
Currency The 3-letter ISO 4217 currency code for the booking.
DailyRate Average per day rate for the hotel. If the rate varies over the duration, it can be specified using the charges model.
DateCancelledUtc The date the booking was cancelled, in UTC. Format: YYYY-MM-DDThh:mm:ss
DateCreatedUtc The date the booking was created, in UTC. Format: YYYY-MM-DDThh:mm:ss
DateModifiedUtc The date the booking was modified, in UTC. Format: YYYY-MM-DDThh:mm:ss
EndDateUtc The booking ending time and date, in UTC. Format: YYYY-MM-DDThh:mm:ss
HotelPropertyId The hotel's property ID.
Notes Additional information about the booking.
NumPersons The number of people the booking is for.
NumRooms The number of rooms the booking is for.
PhoneNumber The phone number for the booking.
RateCode The rate code for the booking.
RoomDescription The room description for the booking. Max Length: 200
RoomType The room type for the booking.
SpecialInstructions Additional instructions regarding the booking. Max Length: 256
StartAddress The starting address of the booking.
StartAddress2 The starting address for the booking.
StartCity The starting address for the booking.
StartCountry The starting address for the booking.
StartLatitude The latitude for the starting location of the booking.
StartLongitude The longitude for the starting location of the booking.
StartPostalCode The starting address for the booking.
StartState The starting address for the booking.
StartDateUtc The booking starting time and date, in UTC. Format: YYYY-MM-DDThh:mm:ss
TimeZone The time zone of the booking. Format: One of the supported Olson or Windows Time Zones.
TotalRate The total rate amount of the booking.

Additional Elements - Optional

Element Description
EndCityCode The IATA airport code for the ending address for the booking.
DiscountCode The discount code for the booking.
FrequentTravelerId The traveler’s ID for the frequent traveler reward program.
HadDeposit Whether the booking had a deposit. Format: true/false
IsUpgradeAllowed Whether the booking can be upgraded. Format: true/false
ModificationCode The code for the modification to the booking.
PartnerMembershipId The membership ID of the partner associated with the booking.
PassiveType The type of the booking.
RateAccess The rate access for the booking.
RateType The rate type for the booking.
UpgradedDateTime The date and time the booking was upgraded. Format: YYYY-MM-DDThh:mm:ss
VendorFlags Semi-colon-delimited list of flags for free hotel service flags. E.g. free breakfast (FB), internet (FI), Parking (FP), etc. If they were all present they can be concatenated as - FB;FI;FP;
VendorName The name of the vendor. When using the Unknown Vendor Code ($$), this value appears as the vendor in the itinerary.

Dining Booking Elements

Core Elements - Required

Element Description
ConfirmationNumber The confirmation number from the vendor.

Core Elements - Optional

Element Description
CancellationNumber The cancellation number from the vendor. This field should be set when you cancel a segment.
Charges The charges for this booking. Refer to the Charges Child Elements table.
DateCancelledUtc The date the booking was cancelled, in UTC. Format: YYYY-MM-DDThh:mm:ss
DateCreatedUtc The date the booking was created, in UTC. Format: YYYY-MM-DDThh:mm:ss
DateModifiedUtc The date the booking was modified, in UTC. Format: YYYY-MM-DDThh:mm:ss
EndDateLocal The booking ending time and date, in the booking location's local time. Format: YYYY-MM-DDThh:mm:ss
EndDateUtc The booking ending time and date, in UTC. Format: YYYY-MM-DDThh:mm:ss
FrequentTravelerId The loyalty program ID for the user.
IsUpgradeAllowed Whether the booking can be upgraded. Format: true/false
Name The name of the restaurant. Maximum length: 80
Notes Additional information about the booking.
NumPersons The number of persons for the booking.
PhoneNumber The restaurant phone number.
RestaurantId The booking vendor’s restaurant ID. Maximum length: 50
StartAddress The restaurant address. Maximum length: 80
StartAddress2 The restaurant address. Maximum length: 80
StartCity The restaurant address. Maximum length: 50
StartCountry The restaurant address.
StartDateLocal The booking starting time and date, in the booking location's local time. Format: YYYY-MM-DDThh:mm:ss
StartDateUtc The booking starting time and date, in UTC. Format: YYYY-MM-DDThh:mm:ss
StartLatitude The latitude of the restaurant.
StartLongitude The longitude of the restaurant.
StartPostalCode The restaurant address. Maximum length: 24
StartState The restaurant address. Maximum length: 50
Status The status of the segment.
TimeZone The time zone of the booking. Format: One of the supported Olson or Windows Time Zones.
UpgradedDateTime The date and time the booking was upgraded. Format: YYYY-MM-DDThh:mm:ss
Vendor The two letter GDS vendor code.
VendorName The name of the vendor. When using the Unknown Vendor Code ($$), this value appears as the vendor in the itinerary.

Ride Booking Elements

Core Elements - Required

Element Description
ConfirmationNumber The confirmation number from the vendor.
EndCityCode The ending IATA airport code of the booking.
StartCityCode The starting IATA airport code of the booking.
Vendor The two letter GDS vendor code. One of the following vendor codes:

Vendor Codes

Code Description
$R RideCharge
AL AddisonLee
DG DeemGroundLimo
GC GroundScope
GS GroundSpan
LC Limoscom
SQ SummitQwest
SW SummitQwest
TD Tandem
TV Transvip
$$ unknown

Core Elements - Optional

Element Description
CancellationNumber The cancellation number from the vendor. This field should be set when you cancel a segment.
CancellationPolicy The cancellation policy from the vendor.
Currency The 3-letter ISO 4217 currency code for the booking.
DateCancelledUtc The date the booking was cancelled, in UTC. Format: YYYY-MM-DDThh:mm:ss
DateCreatedUtc The date the booking was created, in UTC. Format: YYYY-MM-DDThh:mm:ss
DateModifiedUtc The date the booking was modified, in UTC. Format: YYYY-MM-DDThh:mm:ss
DropoffInstructions Instructions regarding the booking.
Duration The duration of the booking.
EndAddress The ending address of the booking.
EndAddress2 The ending address of the booking.
EndCity The ending address of the booking.
EndCountry The ending address of the booking.
EndDateLocal The booking ending time and date, in the booking location's local time. Format: YYYY-MM-DDThh:mm:ss
EndDateUtc The booking ending time and date, in UTC. Format: YYYY-MM-DDThh:mm:ss
EndLatitude The latitude for the ending location of the booking.
EndLocation The ending location of the booking.
EndLocationCode The ending location code of the booking.
EndLocationName The ending location name of the booking.
EndLongitude The longitude of the ending point of the booking.
EndPostalCode The ending address of the booking.
EndState The ending address of the booking.
IsPersonal Whether the segment is for personal travel. Format: true/false.
IsUpgradeAllowed Whether the booking can be upgraded. Format: true/false
MeetingInstructions The instructions for the meeting location of the booking.
Miles The number of miles for the booking.
Name The name on the booking.
Notes Additional information about the booking.
NumberOfHours The number of hours of the booking.
NumPersons The number of people included in the booking.
OperatedByVendor The operated by vendor for the booking.
PassiveCityCode The passive city code of the booking.
PhoneNumber The ride vendor phone number.
PickupInstructions Instructions regarding the booking.
Rate The rate for the booking.
RateDescription The rate description for the booking.
RateNotes The rate notes for the booking.
RateType The rate type for the booking.
ReservationId The booking vendor’s reservation ID.
SpecialInstructions The special instructions for the ride. Max Length: 256
StartAddress The starting address of the booking.
StartAddress2 The starting address of the booking.
StartCity The starting address of the booking.
StartCountry The starting address of the booking.
StartDateLocal The booking starting time and date, in the booking location's local time. Format: YYYY-MM-DDThh:mm:ss
StartDateUtc The booking starting time and date, in UTC. Format: YYYY-MM-DDThh:mm:ss
StartLatitude The latitude of the booking start location.
StartLocation The starting location of the booking.
StartLocationCode The code of the starting location of the booking.
StartLocationName The name of the starting location of the booking.
StartLongitude The longitude of the booking start location.
StartPostalCode The starting address of the booking.
StartState The starting address of the booking.
Status The status of the segment.
TimeZone The time zone of the booking. Format: One of the supported Olson or Windows Time Zones.
UpgradedDateTime The date and time the booking was upgraded. Format: YYYY-MM-DDThh:mm:ss
VendorName The name of the vendor. When using the Unknown Vendor Code ($$), this value appears as the vendor in the itinerary.
Charges The charges for this booking. Refer to the Charges Child Elements table.

Rail Booking Elements

Core Elements - Required

Element Description
ConfirmationNumber The confirmation number from the vendor.
StartDateLocal The starting date of travel for this segment, in the local time of to the starting point. Format: YYYY-MM-DDThh:mm:ss

Core Elements - Optional

Element Description
Amenities The booked amenities.
Cabin The cabin identifier.
CancellationNumber The cancellation number from the vendor. This field should be set when you cancel a segment.
CarbonEmissionLbs The pounds of carbon emission for this booking.
CarbonModel The model used to calculate the carbon emissions.
ClassOfService The class of the booking.
Currency The 3-letter ISO 4217 currency code for the booking.
DateCancelledUtc The date the booking was cancelled, in UTC. Format: YYYY-MM-DDThh:mm:ss
DateCreatedUtc The date the booking was created, in UTC. Format: YYYY-MM-DDThh:mm:ss
DateModifiedUtc The date the booking was modified, in UTC. Format: YYYY-MM-DDThh:mm:ss
DiscountCode The discount code for the booking.
Duration The duration of the trip booked.
EndCity The end city for the rail trip.
EndCityCode The IATA airport code for the end city of the trip.
EndCountry The country code for the booking.
EndDateLocal The booking ending time and date, in the booking location's local time. Format: YYYY-MM-DDThh:mm:ss
EndDateUtc The booking ending time and date, in UTC. Format: YYYY-MM-DDThh:mm:ss
EndLatitude The latitude of the ending point of the booking.
EndLongitude The longitude of the ending point of the booking.
EndPlatform The ending platform location of the booking.
EndRailStation The code for the ending station of the booking.
EndRailStationName The name of the ending station of the booking.
ETicket The e-ticket number.
FareType The type of fare on the rail booking.
FrequentTravelerId The traveler’s ID for the frequent traveler reward program.
IsUpgradeAllowed Whether the booking can be upgraded. Format: true/false
LegId The trip leg ID.
Meals The booked meals.
Miles The number of miles booked.
Notes Additional information about the booking.
NumPersons The number of persons booked for the trip.
NumStops The number of stops in the booking.
OperatedByTrainNumber The train identifier of the operating vendor of the booked trip.
OperatedByVendor The operating vendor of the booked trip.
RateCode The vendor's code for the rate of the booking.
RouteRestrictCode The code to restrict the route of the booking.
SpecialInstructions The instructions for the booking. Max Length: 256
StartCity The starting city of the booking.
StartCityCode The IATA airport code for the starting city of the booking.
StartCountry The starting country of the booking.
StartDateUtc The starting date of travel for this segment, in UTC. Format: YYYY-MM-DDThh:mm:ss
StartLatitude The latitude of the starting location of the booking.
StartLongitude The longitude of the starting location of the booking.
StartPlatform The starting platform location of the booking.
StartRailStation The code of the starting station of the booking.
StartRailStationName The name of the starting station of the booking.
Status The booking status.
TimeZone The time zone of the booking. Format: One of the supported Olson or Windows Time Zones.
TotalRate The total rate amount of the booking.
TrainNumber The number for the booked train.
TrainTypeCode The code for the type of train used in the booking.
TrainTypeName The name of the type of train used in the booking.
TransportMode The transport mode of the booking.
UpgradedDateTime The date and time the booking was upgraded. Format: YYYY-MM-DDThh:mm:ss
Vendor The two letter GDS vendor code.
VendorName The name of the vendor. When using the Unknown Vendor Code ($$), this value appears as the vendor in the itinerary.
WagonNumber The wagon number of the train car.
Charges The charges for this booking. Refer to the Charges Child Elements table.
Seats The booked seats. This parent element contains a RailSeat element for each included seat. The RailSeat element has the following child elements:

RailSeat Child Elements

Element Description
Amenities The amenities for the seat.
BerthPosition The berth location of the seat.
Deck Which deck the seat is on.
FacingForward Whether the seat is facing forward.
FareSpaceComfort The space around the seat.
PassengerRph Which passenger the seat is assigned to.
SeatNumber The number of the seat.
SeatPosition The location of the seat.
SpaceType The type of space around the seat.
Status The status of the seat booking.
WagonNumber The number of the wagon the seat is on.
WagonType The type of wagon the seat is on.

Parking Booking Elements

Core Elements - Required

Element Description
ConfirmationNumber The confirmation number from the vendor.
StartDateLocal The starting date of travel for this segment, in the local time of to the starting point. Format: YYYY-MM-DDThh:mm:ss

Core Elements - Optional

Element Description
CancellationNumber The cancellation number from the vendor. This field should be set when you cancel a segment.
ClassOfService The class of the booking.
Currency The 3-letter ISO 4217 currency code for the booking.
DateCancelledUtc The date the booking was cancelled, in UTC. Format: YYYY-MM-DDThh:mm:ss
DateCreatedUtc The date the booking was created, in UTC. Format: YYYY-MM-DDThh:mm:ss
DateModifiedUtc The date the booking was modified, in UTC. Format: YYYY-MM-DDThh:mm:ss
EndDateLocal The booking ending time and date, in the booking location's local time. Format: YYYY-MM-DDThh:mm:ss
EndDateUtc The booking ending time and date, in UTC. Format: YYYY-MM-DDThh:mm:ss
FrequentTravelerId The traveler’s ID for the frequent traveler reward program.
IsUpgradeAllowed Whether the booking can be upgraded. Format: true/false
Notes Additional information about the booking.
OperatedByVendor The operating vendor of the booking.
ParkingLocationId The location of the parking booking.
PhoneNumber The parking phone number.
Pin The PIN number for the booking.
RateCode The vendor's code for the rate of the booking.
StartAddress The starting address of the booking.
StartAddress2 The starting address of the booking.
StartCity The starting address of the booking.
StartCityCode The IATA airport code for the starting city of the booking.
StartCountry The starting address of the booking.
StartDateUtc The starting date of travel for this segment, in UTC. Format: YYYY-MM-DDThh:mm:ss
StartLocation The parking location.
StartPostalCode The starting address of the booking. Maximum length: 24
StartState The starting address of the booking. Maximum length: 50
Status The booking status.
TimeZone The time zone of the booking. Format: One of the supported Olson or Windows Time Zones.
TotalRate The total rate amount of the booking.
UpgradedDateTime The date and time the booking was upgraded. Format: YYYY-MM-DDThh:mm:ss
Vendor The two letter GDS vendor code.
VendorName The name of the vendor. When using the Unknown Vendor Code ($$), this value appears as the vendor in the itinerary.
Charges The charges for this booking. Refer to the Charges Child Elements table.

Travel Booking

NOTE: This booking type is used by the Concur Travel Request product to store the main destination for the trip without specifying a transport type.

Core Elements - Required

Element Description
EndDateLocal The booking ending time and date, in the booking location's local time. Format: YYYY-MM-DDThh:mm:ss
StartCity The starting address of the booking.
StartCityCode The IATA airport code for the starting city of the booking.
StartDateLocal The starting date of travel for this segment, in the local time of to the starting point. Format: YYYY-MM-DDThh:mm:ss

Core Elements - Optional

Element Description
CancellationNumber The cancellation number from the vendor. This field should be set when you cancel a segment.
ConfirmationNumber The confirmation number from the vendor.
Currency The 3-letter ISO 4217 currency code for the booking.
DailyRate Average per day rate for the booking. If the rate varies over the duration, it can be specified using the charges model.
DateCancelledUtc The date the booking was cancelled, in UTC. Format: YYYY-MM-DDThh:mm:ss
DateCreatedUtc The date the booking was created, in UTC. Format: YYYY-MM-DDThh:mm:ss
DateModifiedUtc The date the booking was modified, in UTC. Format: YYYY-MM-DDThh:mm:ss
EndAddress The ending address of the booking.
EndAddress2 The ending address of the booking.
EndCity The ending address of the booking.
EndCityCode The IATA airport code for the ending city of the booking.
EndCountry The ending address of the booking.
EndDateUtc The booking ending time and date, in UTC. Format: YYYY-MM-DDThh:mm:ss
EndLatitude The latitude for the ending location of the booking.
EndLocation The ending location of the booking.
EndLongitude The longitude of the ending point of the booking.
EndPostalCode The ending address of the booking.
EndState The ending address of the booking.
TransportMode The transport mode of the booking.
Notes Additional information about the booking.
NumPersons The number of persons booked for the trip.
PhoneNumber The parking phone number.
SpecialInstructions The instructions for the booking. Max Length: 256
StartAddress The starting address of the booking.
StartAddress2 The starting address of the booking.
StartCity The starting address of the booking.
StartCityCode The IATA airport code for the starting city of the booking.
StartCountry The starting address of the booking.
StartDateUtc The starting date of travel for this segment, in UTC. Format: YYYY-MM-DDThh:mm:ss
StartLatitude The latitude of the starting location of the booking.
StartLongitude The longitude of the starting location of the booking.
StartPostalCode The starting address of the booking. Maximum length: 24
StartState The starting address of the booking. Maximum length: 50
Status The booking status.
TimeZone The time zone of the booking. Format: One of the supported Olson or Windows Time Zones.
TotalRate The total rate amount of the booking.
Vendor The two letter GDS vendor code.
VendorName The name of the vendor. When using the Unknown Vendor Code ($$), this value appears as the vendor in the itinerary.
Charges The charges for this booking. Refer to the Charges Child Elements table.
Seats The seats for the booking. This parent element contains an TravelSeat element for each included seat. The TravelSeat element contains the following child elements:
TravelSeat Elements
Element Description
PassengerRph The passenger assigned to the seat.
SeatNumber The number of the seat.

Charges Child Elements

Core Elements - Required
Percent - The Percent of Fixed Charges

This parent element contains the following child elements:

Element Description
Amount The total amount for the rate for the booking.
Currency The 3-letter ISO 4217 currency code for the total amount.
Description The description for the rate.
IsPaid Whether the rate has been paid. Format: true/false.
IsPrimary Indicates whether the charge is the Primary or Main rate. For example, if one of the rates is the actual rate and the rest are penalties, the actual rate should be set as IsPrimary. Only one charge in a set should be primary. Format: true/false.
SemanticsCode Indicates the charge category for the line item.
SemanticsVendorType The vendor type: H=Hotel, C=Car, A=Air, G=Ground, R=Rail
StartDateLocal The start date of the booking, in the user's local time. Format: YYYY-MM-DDThh:mm:ss
Vendor The vendor for the booking charge.
VendorChargeCode The vendor's code for the charge
Fixed - The Fixed Charges

This parent element contains the following child elements:

Element Description
Currency The 3-letter ISO 4217 currency code for the total amount.
Description The description for the fixed amount.
IsPaid Whether the fixed amount has been paid. Format: true/false.
IsPrimary Whether the fixed amount is primary. Format: true/false.
SemanticsCode Indicates the charge category for the line item. Refer to the Semantics and Vendor Codes document for more information.
SemanticsVendorType The vendor type: H=Hotel, C=Car, A=Air, G=Ground, R=Rail
StartDateLocal The start date of the booking, in the user's local time. Format: YYYY-MM-DDThh:mm:ss
Vendor The vendor applying the booking charge.
VendorChargeCode The vendor's code for the charge.
Rate - The Rate for the Booking

This parent element contains the following child elements:

Element Description
Amount The total amount for the rate for the booking.
Currency The 3-letter ISO 4217 currency code for the total amount.
Description The description for the rate.
IsPaid Whether the rate has been paid. Format: true/false.
IsPrimary Whether the rate is primary. Format: true/false.
NumUnits The number of units expected for the charge. For instance, 3 days
PerUnit The unit of measure for the charge. Values represent rates like per DAY, WEEK, or MONTH
SemanticsCode Indicates the charge category for the line item. Refer to the Semantics and Vendor Codes document for more information.
SemanticsVendorType The vendor type: H=Hotel, C=Car, A=Air, G=Ground, R=Rail
StartDateLocal The start date of the booking, in the user's local time. Format: YYYY-MM-DDThh:mm:ss
Vendor The vendor for the booking charge.
VendorChargeCode The vendor's code for the charge.
RateWithAllowance - The Rate for the Booking, Including any Travel Allowances

This parent element contains the following child elements:

Element Description
AllowanceAmount The cost of overage fees when the allowance is exceeded. For example, if the allowance is 5000 miles, the cost could be $0.02 per mile. The overage must be in the same currency as the basic rate.
AllowanceIsUnlimited Whether the allowance is unlimited. Format: true/false.
AllowanceNumUnits The number of units for the allowance associated with the charge. For example, 5000 miles.
AllowanceUnit The unit of measure for the allowance associated with the charge. For example, a car weekly rate might allow 5000 miles included in the rate.
Amount The total amount for the rate for the booking.
Currency The 3-letter ISO 4217 currency code for the total amount.
Description The description for the rate.
IsPaid Whether the rate has been paid. Format: true/false.
IsPrimary Indicates whether the charge is the Primary or Main rate. For example, if one of the rates is the actual rate and the rest are penalties, the actual rate should be set as IsPrimary. Only one charge in a set should be primary. Format: true/false.
NumUnits The number of units expected for the charge. For instance, 3 days.
PerUnit The unit of measure for the charge. Values represent rates like per DAY, WEEK, or MONTH
SemanticsCode Indicates the charge category for the line item. Refer to the Semantics and Vendor Codes document for more information.
SemanticsVendorType The vendor type: H=Hotel, C=Car, A=Air, G=Ground, R=Rail
StartDateLocal The start date of the booking, in the user's local time. Format: YYYY-MM-DDThh:mm:ss
Vendor The vendor for the booking charge.
VendorChargeCode The vendor's code for the charge.

Time Zone Formats

Olson Time Zones

Africa/Cairo Africa/Casablanca Africa/Harare Africa/Luanda
Africa/Nairobi Africa/Windhoek America/Anchorage America/Argentina/Buenos_Aires
America/Asuncion America/Bahia America/Bogota America/Buenos_Aires
America/Caracas America/Chicago America/Chihuahua America/Denver
America/Godthab America/Guyana America/Halifax America/Indianapolis
America/Los_Angeles America/Manaus America/Mexico_City America/Montevideo
America/New_York America/Phoenix America/Regina America/Santiago
America/Sao_Paulo America/St_Johns America/Swift_Current America/Tijuana
Asia/Almaty Asia/Amman Asia/Baghdad Asia/Baku
Asia/Bangkok Asia/Beirut Asia/Calcutta Asia/Colombo
Asia/Damascus Asia/Dhaka Asia/Irkutsk Asia/Jerusalem
Asia/Kabul Asia/Kamchatka Asia/Karachi Asia/Karachi
Asia/Katmandu Asia/Krasnoyarsk Asia/Magadan Asia/Muscat
Asia/Novosibirsk Asia/Rangoon Asia/Riyadh Asia/Seoul
Asia/Shanghai Asia/Singapore Asia/Taipei Asia/Tbilisi
Asia/Tehran Asia/Tokyo Asia/Ulaanbaatar Asia/Vladivostok
Asia/Yakutsk Asia/Yekaterinburg Asia/Yerevan Atlantic/Azores
Atlantic/Cape_Verde Atlantic/South_Georgia Australia/Adelaide Australia/Brisbane
Australia/Darwin Australia/Hobart Australia/Perth Australia/Sydney
Etc/GMT+12 Etc/GMT-11 Etc/GMT-2 Europe/Athens
Europe/Berlin Europe/Helsinki Europe/Istanbul Europe/Kaliningrad
Europe/London Europe/Minsk Europe/Moscow Europe/Paris
Europe/Prague Europe/Sarajevo GMT GMT-1200
Indian/Mauritius Pacific/Apia Pacific/Auckland Pacific/Fiji
Pacific/Guadalcanal Pacific/Guam Pacific/Honolulu Pacific/Tongatapu
UTC

Windows Time Zones

Africa/Cairo Africa/Casablanca Africa/Harare Africa/Luanda
Africa/Nairobi Africa/Windhoek America/Anchorage America/Argentina/Buenos_Aires
America/Asuncion America/Bahia America/Bogota America/Buenos_Aires
America/Caracas America/Chicago America/Chihuahua America/Denver
America/Godthab America/Guyana America/Halifax America/Indianapolis
America/Los_Angeles America/Manaus America/Mexico_City America/Montevideo
America/New_York America/Phoenix America/Regina America/Santiago
America/Sao_Paulo America/St_Johns America/Swift_Current America/Tijuana
Asia/Almaty Asia/Amman Asia/Baghdad Asia/Baku
Asia/Bangkok Asia/Beirut Asia/Calcutta Asia/Colombo
Asia/Damascus Asia/Dhaka Asia/Irkutsk Asia/Jerusalem
Asia/Kabul Asia/Kamchatka Asia/Karachi Asia/Karachi
Asia/Katmandu Asia/Krasnoyarsk Asia/Magadan Asia/Muscat
Asia/Novosibirsk Asia/Rangoon Asia/Riyadh Asia/Seoul
Asia/Shanghai Asia/Singapore Asia/Taipei Asia/Tbilisi
Asia/Tehran Asia/Tokyo Asia/Ulaanbaatar Asia/Vladivostok
Asia/Yakutsk Asia/Yekaterinburg Asia/Yerevan Atlantic/Azores
Atlantic/Cape_Verde Atlantic/South_Georgia Australia/Adelaide Australia/Brisbane
Australia/Darwin Australia/Hobart Australia/Perth Australia/Sydney
Etc/GMT+12 Etc/GMT-11 Etc/GMT-2 Europe/Athens
Europe/Berlin Europe/Helsinki Europe/Istanbul Europe/Kaliningrad
Europe/London Europe/Minsk Europe/Moscow Europe/Paris
Europe/Prague Europe/Sarajevo GMT GMT-1200
Indian/Mauritius Pacific/Apia Pacific/Auckland Pacific/Fiji
Pacific/Guadalcanal Pacific/Guam Pacific/Honolulu Pacific/Tongatapu
UTC

Trip Endpoint

Trips

The Trips resource represents itineraries in the Concur Travel system. TripLink suppliers use this resource to display a subset of the full booking fields.

Version

1.1

URI

/travel/trip/v1.1/{query_parameters}

Scope

In order to obtain itinerary data when making Itinerary API calls, the value of the OAuth scope parameter must be set to: ITINER

Operations

Get Trip Summaries

The Get Itinerary Summaries endpoint is used for retrieving trip summaries for the traveler whose account is associated with the OAuth access token used to make the API call. This endpoint can also be used to get trip summaries for a different user or the whole company. This is usually done when a Travel Management Company (TMC) needs to get trip summaries on behalf of a user or company.

Best Practices

Request

GET /travel/trip/v1.1/{query_parameters}

Query Parameters

All query parameters are optional.

To identify a specific user by login ID or XMLSyncID, you can specify the following request parameters:

Parameter Name Parameter Type Data Type Description
startDate date dateTime The URL-encoded start date (in Coordinated Universal Time, or UTC) for the trip. Format: YYYY-MM-DD. If no query parameters are provided, the start date is set to today's date - 30 days. The request will only return trips that are ongoing during the provided dates, either starting on the date, or starting before the date and ongoing during the provided date.
endDate date dateTime The URL-encoded UTC end date for the trip. Format: YYYY-MM-DD. If no query parameters are provided, the end date is set to today's date + 12 months. The request will only return trips that are ongoing during the provided dates, either ending on the date, or starting before the date and ongoing during the provided date.
createdAfterDate date dateTime The URL-encoded UTC date for when the trip was created. The query string will return trips created on or after this date. Used with the createdBeforeDate for finding trips created during a date range. Format: YYYY-MM-DD.
createdBeforeDate date dateTime The URL-encoded UTC date for when the trip was created. The query string will return trips created on or before this date. Used with the createdAfterDate for finding trips created during a date range. Format: YYYY-MM-DD.
lastModifiedDate date dateTime The last modified UTC date of the trips and their associated bookings. This query string will return only the trips where the trip or any of its associated bookings have a last modified date that is greater or equal to the supplied time. The provided date/time can be anytime between now and the first date of trip creation in the database. The format is either the date or the date and time combined.
bookingType type string The trip includes at least one booking of this type. Format: Air, Car, Dining, Hotel, Parking, Rail, or Ride.
userid_type=login userid string The loginID is the user's SAP Concur login ID. This parameter can only be used if the OAuth consumer has one of the user roles listed above.
userid_value userid string The userid_value of ALL can be sent to get trip summaries for all users at the company. This parameter can only be used if the OAuth consumer has one of the user roles listed above.
includeMetadata true/false string The includeMetadata query parameter combined with the ItemsPerPage and Page query parameters cause the response to be divided into pages. The response is wrapped in a ConcurResponse parent element, with both the response details and the paging metadata included. If the ItemsPerPage query parameter is not sent, the response will default to 200 if the Page query parameter is sent, or 1000 if the Page query parameter is not set. If the Page query parameter is not sent, the response will default to page 1.
ItemsPerPage number integer The includeMetadata query parameter combined with the ItemsPerPage and Page query parameters will cause the response to be divided into pages. The response will be wrapped in a ConcurResponse parent element, with both the response details and the paging metadata included. If the ItemsPerPage query parameter is not sent, the response will default to 200 if the Page query parameter is sent, or 1000 if the Page query parameter is not set. If the Page query parameter is not sent, the response will default to page 1.
includeVirtualTrip flag integer Virtual trips are segments booked offline through the Concur Request product. Set the includeVirtualTrip query parameter to 1 to include those trips in the list.
includeCanceledTrips true/false string The includeCanceledTrips query parameter will cause the request to also return trips with a status of Canceled. When this query parameter is set to true, the response will include the TripStatus element.
includeGuestBookings true/false string The includeGuestBookings query parameter will cause the request to show guest bookings if set to true. It is set to false by default.

Here are some examples of how to format GET requests using a combination of these query parameters:

https://www.concursolutions.com/api/travel/trip/v1.1/?startDate={_startdate_}&endDate={_enddate_}_&_createdAfterDate={_date_}&createdBeforeDate={_date_}&lastModifiedDate={_date_}&bookingType={_type_}&userid_type=login&userid_value=ALL

The access token used to make the API call must be associated with an account that has the Admin user role.

https://www.concursolutions.com/api/travel/trip/v1.1/?startDate={_startdate_}&endDate={_enddate_}_&_createdAfterDate={_date_}&createdBeforeDate={_date_}&lastModifiedDate={_date_}&bookingType={_type_}

The access token used to make the API call is associated with the account for the app making the call.

https://www.concursolutions.com/api/travel/trip/v1.1/?startDate={_startdate_}&endDate={_enddate_}_&_createdAfterDate={_date_}&createdBeforeDate={_date_}&lastModifiedDate={_date_}&bookingType={_type_}&userid_type=login_id&userid_value={_loginID_}

The access token used to make the API call is associated with the SAP Concur account with the specified login credentials.

Headers

Authorization Header (Required)

Authorization: OAuth {access_token} Where access_token is the OAuth 2.0 access token of the user whose itinerary information you want to retrieve. If you want to access company-wide itinerary information, the SAP Concur user account associated with the OAuth 2.0 access token must have one of these roles: Web Services Administrator for Professional or Can Administer for Standard.

Accept Header (optional)

application/xml

Get Trip Summaries Response Schema

The response returns an ItineraryInfoList parent element with an ItineraryInfo child element for each trip summary for the specified traveler. If the includeMetadata and ItemsPerPage query parameters are included in the request, the response will include a ConnectResponse parent element which contains a MetaData element with paging information and a Data element with an ItineraryInfoList child element. The response for this operation can be divided into pages for easier processing.

Data Elements

Element Name Data Type Description
ItineraryInfoList element Parent element with an ItineraryInfo child element for each trip summary for the specified traveler.

ItineraryInfoList Elements

Element Name Data Type Description
ItineraryInfo element Parent element with the information about an itinerary for the specified user.

ItineraryInfo Elements

Element Name Data Type Description
TripId string Encrypted trip identifier value.
TripName string Name of the trip.
TripStatus string The status of the trip. This element only appears if the includeCanceledTrips query parameter is used in the request.
StartDateLocal dateTime The start date of the trip in the starting location’s timezone. Format: YYYY-MM-DDThh:mm:ss.
EndDateLocal dateTime The end date of the trip in the ending location’s timezone. Format: YYYY-MM-DDThh:mm:ss.
DateModifiedUtc dateTime The UTC date that this trip was last modified. Format: YYYY-MM-DDThh:mm:ss.
UserLoginId string The user's login to SAP Concur. This element appears in the response of the GET /api/travel/trip/v1.1 operation when the OAuth 2.0 is access token is associated with an SAP Concur account with one of these roles: Web Services Administrator for Professional or Can Administer for Standard.
id string Trip ID URI with encrypted ID.

Metadata Element

The parent element of the paging information.

Paging Elements

Element Name Data Type Description
TotalPages integer The total number of pages the query returned.
TotalItems integer The total number of itineraries the query returned.
CurrentPage integer The page number for the set of results in the current response.
ItemsPerPage integer The number of items set to display per page.
PreviousPageURL string The URI to the previous page of results. This element will be empty when there are no previous pages.
NextPageURL string The URI to the next set of results. This element will be empty when there are no next pages.

Examples

Example 1: Get Trip Summaries by Start and End Date

Request

GET /api/travel/trip/v1.1/?startDate=2012%2F02%2F01&endDate=2013%2F12%2F31 HTTP/1.1
Host: www.concursolutions.com
Authorization: OAuth {access token}
...

Response

HTTP/1.1 200 OK
Content-Type: application/xml
...

<?xml version="1.0" encoding="utf-8"?>
<ItineraryInfoList xmlns="http://www.concursolutions.com/api/travel/trip/2010/06" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <ItineraryInfo>
        <TripId>naIzQJ0y2DBWjCIQOb2SHTsozwBsHDkdP</TripId>
        <TripName>Trip from Baltimore to New York</TripName>
        <StartDateLocal>2012-02-15T09:00:00</StartDateLocal>
        <EndDateLocal>2012-02-21T17:30:00</EndDateLocal>
        <UserLoginId>cm@example.com</UserLoginId>
        <DateModifiedUtc>2012-02-14T17:13:07</DateModifiedUtc>
        <id>https://www.concursolutions.com/api/travel/trip/v1.1/naIzQJ0y2DBWjCIQOb2SHTsozwBsHDkdP</id>
    </ItineraryInfo>
    <ItineraryInfo>
        <TripId>I2uwiJJw8r7Owl3IWlSie9WIelxhAhwiL</TripId>
        <TripName>Trip from Baltimore to Seattle</TripName>
        <StartDateLocal>2012-03-26T09:00:00</StartDateLocal>
        <EndDateLocal>2012-03-29T17:30:00</EndDateLocal>
        <DateModifiedUtc>2012-03-24T19:00:00</DateModifiedUtc>
        <UserLoginId>cm@example.com</UserLoginId>
        <id>https://www.concursolutions.com/api/travel/trip/v1.1/I2uwiJJw8r7Owl3IWlSie9WIelxhAhwiL</id>
    </ItineraryInfo>
</ItineraryInfoList>

Example 2: Get Trip Summary by Booking Type and Start Date Request

This request returns trip summaries for trips that started by the specified date for the specified booking type.

Request

GET /api/travel/trip/v1.1/?startDate=2015%2F01%2F01&bookingType=Air HTTP/1.1
Host: www.concursolutions.com
Authorization: OAuth {access token}
...

Response

HTTP/1.1 200 OK
Content-Type: application/xml
...

<?xml version="1.0" encoding="utf-8"?>
<ItineraryInfoList xmlns="http://www.concursolutions.com/api/travel/trip/2010/06" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <ItineraryInfo>
        <TripId>I2uwiJJw8r7OwCIQOb2SHTsozwBsSie9W</TripId>
        <TripName>Trip by air from Seattle to San Francisco</TripName>
        <StartDateLocal>2015-01-01T12:30:00</StartDateLocal>
        <EndDateLocal>2015-01-05T10:30:00</EndDateLocal>
        <UserLoginId>cm@example.com</UserLoginId>
        <DateModifiedUtc>2014-12-23T11:10:00</DateModifiedUtc>
        <id>https://www.concursolutions.com/api/travel/trip/
        v1.1/I2uwiJJw8r7OwCIQOb2SHTsozwBsSie9W</id>
    </ItineraryInfo>
</ItineraryInfoList>

Example 3: Get Trip Summary by Created Date

This requests returns trip summaries created after the specified date.

Request

GET /api/travel/trip/v1.1/?createdAfterDate=2015%2F02%2F13 HTTP/1.1
Host: www.concursolutions.com
Authorization: OAuth {access token}

Response

HTTP/1.1 200 OK
Content-Type: application/xml
...

<?xml version="1.0" encoding="utf-8"?>
<ItineraryInfoList xmlns="http://www.concursolutions.com/api/travel/trip/2010/06" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <ItineraryInfo>
        <TripId>BWjCIJJw8r7OwCIQOb2SHTsozwBsWlSie9</TripId>
        <TripName>Trip by air from Los Angeles to Mexico City</TripName>
        <StartDateLocal>2015-03-09T18:45:00</StartDateLocal>
        <EndDateLocal>2015-03-30T08:00:00</EndDateLocal>
        <UserLoginId>cm@example.com</UserLoginId>
        <DateModifiedUtc>2015-01-28T09:30:00</DateModifiedUtc>
        <id>https://www.concursolutions.com/api/travel/trip/
        v1.1/BWjCIJJw8r7OwCIQOb2SHTsozwBsWlSie9</id>
    </ItineraryInfo>
</ItineraryInfoList>

Example 4: Get Trip Summary with Paging

This request is used for dividing the response into pages for easier processing.

Request

GET /api/travel/trip/v1.1/?createdAfterDate=2012%2F02%2F01&includeMetadata=true&ItemsPerPage=2&Page=1 HTTP/1.1
Host: www.concursolutions.com
Authorization: OAuth {access token}

Response

The response returns a ConnectResponse parent element which contains a MetaData element with paging information and a Data element with an ItineraryInfoList child element.

HTTP/1.1 200 OK
Content-Type: application/xml
...

<ConnectResponse>
    <Metadata>
        <Paging>
            <TotalPages>38</TotalPages>
            <TotalItems>187</TotalItems>
            <CurrentPage>2</CurrentPage>
            <ItemsPerPage>2</ItemsPerPage>
            <PreviousPageURL>https://www.concursolutions.com/api/travel/trip/v1.1/?
                createdAfterDate=2012%2F02%2F01&amp;
                itemsPerPage=5&amp;page=3&amp;includeMetaData=true</PreviousPageURL>
            <NextPageURL>https://www.concursolutions.com/api/travel/trip/v1.1/?
                createdAfterDate=2012%2F02%2F01&amp;
                itemsPerPage=5&amp;page=1&amp;includeMetaData=true</NextPageURL>
        </Paging>
    </Metadata>
    <Data>
        <ItineraryInfoList xmlns="http://www.concursolutions.com/api/travel/trip/2010/06" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
            <ItineraryInfo>
                <TripId>naIzQJ0y2DBWjCIQOb2SHTsozwBsHDkdP</TripId>
                <TripName>Trip from Baltimore to New York</TripName>
                <StartDateLocal>2012-02-15T09:00:00</StartDateLocal>
                <EndDateLocal>2012-02-21T17:30:00</EndDateLocal>
                <UserLoginId>cm@example.com</UserLoginId>
                <DateModifiedUtc>2012-02-14T17:13:07</DateModifiedUtc>
                <id>https://www.concursolutions.com/api/travel/trip/v1.1/naIzQJ0y2DBWjCIQOb2SHTsozwBsHDkdP</id>
            </ItineraryInfo>
            <ItineraryInfo>
                <TripId>I2uwiJJw8r7Owl3IWlSie9WIelxhAhwiL</TripId>
                <TripName>Trip from Baltimore to Seattle</TripName>
                <StartDateLocal>2012-03-26T09:00:00</StartDateLocal>
                <EndDateLocal>2012-03-29T17:30:00</EndDateLocal>
                <DateModifiedUtc>2012-03-24T19:00:00</DateModifiedUtc>
                <UserLoginId>cm@example.com</UserLoginId>
                <id>https://www.concursolutions.com/api/travel/trip/v1.1/I2uwiJJw8r7Owl3IWlSie9WIelxhAhwiL</id>
            </ItineraryInfo>
        </ItineraryInfoList>
    </Data>
</ConnectResponse>

Get Trip Details

The Get Itinerary Details endpoint is used for getting details for the specified trip. The elements included in the response vary as follows:

This topic describes the full set of possible elements that can be returned. No itinerary can contain all of the possible elements, so the response will always be a subset of all the possible returned values.

By default, when calling this API, the SAP Concur account associated with the OAuth access token used to make the API call should be the owner of the trip. This endpoint can also be used to get details for trips that the OAuth consumer does not own. This is most often done when a TMC needs to get trip details on behalf of a user. The TMC must be registered with SAP Concur and have an SAP Concur account that has one of the following user roles: Web Services Administrator for Professional, or Can Administer for Standard.

Request

GET /travel/trip/v1.1/trip_ID?[systemFormat=system_format|&userid_type=login|&user_id=login_ID]

Path Parameters

Parameter Name Data Type Description
trip_ID string Required: The identifier for the desired trip. This identifier is returned as the value of the ID element when getting trip summaries. For example, if the returned value of the ID element is I2uwiJJw8r7Owl3IWlSie9WIelxhAhwiL, then the URI for the request is /travel/trip/v1.1/I2uwiJJw8r7Owl3IWlSie9WIelxhAhwi.

Query Parameters

Parameter Name Data Type Description
systemFormat string Optional: Format of the response for a different system. The supported value is Tripit. The format for the request URI using this query parameter is /travel/trip/v1.1/trip_ID?systemFormat=Tripit.
userid_type string Optional: The type of user identification to use. Possible value is: login.
userid_value string Optional: The user's login ID. This parameter must be provided in conjunction with the userid_type parameter. The userid_type and userid_value parameters can only be used if the user account associated with the OAuth 2.0 access token must have an SAP Concur account with one of these roles: Web Services Administrator for Professional or Can Administer for Standard. The format for the request URI using the userid_type and userid_value query parameters is /travel/trip/v1.1/trip_ID?userid_type=login&userid_value=login_ID.

Headers

Authorization Header (Required)

Authorization: OAuth {access_token}
Where access_token is the OAuth 2.0 access token of the user whose itinerary information you want to retrieve. If you want to access company-wide itinerary information, the user account associated with the OAuth 2.0 access token must have an SAP Concur account with one of these roles: Web Services Administrator for Professional or Can Administer for Standard.

Accept Header (Optional)

application/xml

Get Trip Details Response Schema

The response returns subset of the elements described in the following tables depending on the parameters used in the request and the status and details for the itinerary. The response can be formatted for TripIt, using the systemformat query string.

Parent Elements

Element Name Data Type Description
id string Trip ID URI with encrypted ID.
ItinLocator string The itinerary locator. This element is now deprecated and only supported for backward compatibility.
ClientLocator string Represents the unique identifier of the trip in an external (non-Concur) system. Maximum length 32 characters.
ItinSourceName string The itinerary source. Format: TravelSupplier.
TripName string Name of the trip. Maximum length 255 characters.
Comments string Comments for this itinerary. Maximum length 512 characters.
StartDateLocal dateTime The start date of the trip in the starting location’s timezone. Format: YYYY-MM-DDThh:mm:ss.
EndDateLocal dateTime The end date of the trip in the ending location’s timezone. Format: YYYY-MM-DDThh:mm:ss.
DateCreatedUtc dateTime The date that this trip was created, in UTC. Format: YYYY-MM-DDThh:mm:ss.
DateModifiedUtc dateTime The UTC date that this trip was last modified. Format: YYYY-MM-DDThh:mm:ss.
BookedVia string The booking method for the trip.
BookedByFirstName string The first name of the person who booked the trip.
BookedByLastName string The last name of the person who booked the trip.
DateBookedLocal dateTime The date the trip was booked, in the local time of the booking location. Format: YYYY-MM-DDThh:mm:ss.
CancelComments string The comments provided if the itinerary is cancelled. Maximum length: 256 characters.
Description string The trip description. Maximum length: 512 characters.
EndDateUtc dateTime The end date of the trip, in UTC. Format: YYYY-MM-DDThh:mm:ss.
IsPersonal boolean Whether the trip is a Business or Leisure trip. Format: true/false.
ProjectName string The associated project name for the trip. Maximum length: 255 characters.
StartDateUtc dateTime The start date of the trip, in UTC. Format: YYYY-MM-DDThh:mm:ss.
RuleViolations array The list of rule violations associated with the itinerary. This parent element contains a RuleViolation child element for each associated rule violation.
Status string The status of the itinerary. One of the following: 0- Confirmed; 1- Ticketed by agent; 2- Canceled.
Bookings array A parent element that contains a Booking child element for each booking associated with this itinerary.

Booking Element

Element Name Data Type Description
Segments array List of segments in this booking. The child elements included in this element vary depending on whether a TMC, SAP Concur client, third-party developer, or TripLink supplier is requesting the itinerary details: For TMCs, clients, and third-party developers, the Segments element contains one or more Air, Car, Hotel, Dining, Ride, Rail, Parking, or Travel parent elements. For TripLink suppliers, the Segments element contains one or more Air, Car, Hotel, or Ride parent elements.
Passengers array Contains a Passenger child element for each included passenger. For more information on the Passengers element, see Create a New Trip.
RecordLocator string The unique identifier for a booking. This is often six alphanumeric characters, but can have other formats depending on the booking source.
BookingSource string The name of the booking source for this booking. A booking source is a textual name the system uses to track where a booking took place.
DateModifiedUtc dateTime The date the booking was last modified, in UTC. Format: YYYY-MM-DDThh:mm:ss.
DateBookedLocal dateTime The date the booking was created, in the booking location's local time. Format: YYYY-MM-DDThh:mm:ss.
ItinSourceName string The itinerary source. Format: TravelSupplier.
PassengerCount integer The number of passengers included in the booking.

Examples

Example 1: Get Trip Details for a Trip ID

Request

GET /api/travel/trip/v1.1/CNQR1234567890 HTTP/1.1
Host: www.concursolutions.com
Authorization: OAuth {access token}
...

Response

HTTP/1.1 200 OK
Content-Type: application/xml
...

<?xml version="1.0" encoding="utf-8"?>
<Itinerary xmlns="http://www.concursolutions.com/api/travel/trip/2010/06">
    <id>https://www.concursolutions.com/api/travel/trip/v1.1/CNQR1234567890</id>
    <ItinLocator>CNQR1234567890</ItinLocator>
    <ClientLocator>KK-CNQ-1M1P6-5HJ</ClientLocator>
    <ItinSourceName>ConcurTravel</ItinSourceName>
    <TripName>Trip from Dallas to Seattle</TripName>
    <Comments />
    <StartDateLocal>2013-12-21T07:25:00</StartDateLocal>
    <EndDateLocal>2013-12-24T23:59:00</EndDateLocal>
    <DateModifiedUtc>2012-07-24T19:15:52</DateModifiedUtc>
    <BookedVia>EveryGDS</BookedVia>
    <BookedByFirstName>Chris</BookedByFirstName>
    <BookedByLastName>Miller</BookedByLastName>
    <DateBookedLocal>2012-07-24T19:15:52</DateBookedLocal>
    <Bookings>
        <Booking>
            <Segments>
                <Car>
                    <Vendor>CQ</Vendor>
                    <Status>HK</Status>
                    <StartDateLocal>2013-12-21T12:00:00</StartDateLocal>
                    <EndDateLocal>2013-12-24T12:00:00</EndDateLocal>
                    <ConfirmationNumber>F1672664579</ConfirmationNumber>
                    <DateModifiedUtc>2012-07-24T19:15:52</DateModifiedUtc>
                    <StartCityCode>SEA</StartCityCode>
                    <EndCityCode>SEA</EndCityCode>
                    <StartLocation>SEA</StartLocation>
                    <EndLocation>SEA</EndLocation>
                    <Class>E</Class>
                    <Body>C</Body>
                    <Transmission>M</Transmission>
                    <AirCondition>R</AirCondition>
                    <NumCars>1</NumCars>
                    <DiscountCode>346660</DiscountCode>
                    <DailyRate>44.0000</DailyRate>
                    <TotalRate>44.0000</TotalRate>
                    <RateType>D</RateType>
                    <Currency>USD</Currency>
                    <Charges>
                        <Fixed>
                            <Description>Dropoff Fee</Description>
                            <Currency>USD</Currency>
                            <Amount>0.0000</Amount>
                            <IsPrimary>false</IsPrimary>
                            <SemanticsCode>DROPOFFFEE</SemanticsCode>
                            <SemanticsVendorType>C</SemanticsVendorType>
                        </Fixed>
                        <RateWithAllowance>
                            <Currency>USD</Currency>
                            <Amount>44.0000</Amount>
                            <StartDateLocal>2013-12-21T12:00:00</StartDateLocal>
                            <IsPrimary>true</IsPrimary>
                            <SemanticsCode>DAYS</SemanticsCode>
                            <SemanticsVendorType>C</SemanticsVendorType>
                            <PerUnit>DAY</PerUnit>
                            <NumUnits>1.0000</NumUnits>
                            <AllowanceNumUnits>250.0000</AllowanceNumUnits>
                            <AllowanceAmount>0.2400</AllowanceAmount>
                            <AllowanceIsUnlimited>false</AllowanceIsUnlimited>
                        </RateWithAllowance>
                    </Charges>
                </Car>
            </Segments>
            <Passengers>
                <Passenger>
                    <NameFirst>Chris</NameFirst>
                    <NameLast>Miller</NameLast>
                </Passenger>
            </Passengers>
            <RecordLocator>C123456789</RecordLocator>
            <BookingSource>ConcurCars</BookingSource>
            <DateModifiedUtc>2012-07-24T19:15:52</DateModifiedUtc>
            <DateBookedLocal>2013-11-10T13:01:00</DateBookedLocal>
            <ItinSourceName>TravelSupplier</ItinSourceName>
            <PassengerCount>1</PassengerCount>
        </Booking>
        <Booking>
            <Segments>
                <Hotel>
                    <Vendor>CQ</Vendor>
                    <Status>GK</Status>
                    <StartDateLocal>2013-12-21T23:59:00</StartDateLocal>
                    <EndDateLocal>2013-12-24T23:59:00</EndDateLocal>
                    <ConfirmationNumber>3364214265</ConfirmationNumber>
                    <DateModifiedUtc>2012-07-24T19:15:52</DateModifiedUtc>
                    <RateCode>LV4</RateCode>
                    <Name>CONCUR HOTEL</Name>
                    <HotelPropertyId>CONQ</HotelPropertyId>
                    <CheckinTime>00:00</CheckinTime>
                    <CheckoutTime>00:00</CheckoutTime>
                    <NumPersons>1</NumPersons>
                    <NumRooms>1</NumRooms>
                    <CancellationPolicy>Cxl 1 day prior to Arrival</CancellationPolicy>
                    <DailyRate>240.3500</DailyRate>
                    <Currency>USD</Currency>
                    <RoomDescription>1 KING BED ACCESSIBLE ROOM - K1RRC</RoomDescription>
                    <Charges>
                        <Rate>
                            <Currency>USD</Currency>
                            <Amount>240.3500</Amount>
                            <StartDateLocal>2013-12-21T23:59:00</StartDateLocal>
                            <IsPrimary>false</IsPrimary>
                            <SemanticsCode>ROOMRATE</SemanticsCode>
                            <SemanticsVendorType>H</SemanticsVendorType>
                            <PerUnit>DAY</PerUnit>
                            <NumUnits>3.0000</NumUnits>
                        </Rate>
                    </Charges>
                </Hotel>
            </Segments>
            <Passengers>
                <Passenger>
                    <NameFirst>Chris</NameFirst>
                    <NameLast>Miller</NameLast>
                </Passenger>
            </Passengers>
            <RecordLocator>0987654321</RecordLocator>
            <BookingSource>ConcurHotel</BookingSource>
            <DateModifiedUtc>2012-07-24T19:15:52</DateModifiedUtc>
            <DateBookedLocal>2013-11-10T13:01:00</DateBookedLocal>
            <OriginalItinLocator>33491211</OriginalItinLocator>
            <ItinSourceName>ConcurTravel</ItinSourceName>
            <PassengerCount>1</PassengerCount>
        </Booking>
    </Bookings>
</Itinerary>

Example 2: Get Trip Details in TripIt Format

Request

GET /travel/trip/v1.1/73014481752?systemFormat=Tripit HTTP/1.1
Host: www.concursolutions.com
Authorization: OAuth {access token}
...

Response

<?xml version="1.0" encoding="utf-8"?>
<Response>
    <Trip>
        <id>73014481752</id>
        <relative_url>/api/travel/trip/v1.1/73014481752</relative_url>
        <start_date>2013-08-21</start_date>
        <end_date>2013-08-24</end_date>
        <display_name>Strategy Team meeting</display_name>
        <is_private>true</is_private>
    </Trip>
    <AirObject>
        <booking_site_conf_num>RL10001005</booking_site_conf_num>
        <booking_site_name>Concur Travel</booking_site_name>
        <booking_site_phone></booking_site_phone>
        <booking_site_url>https://www.concursolutions.com</booking_site_url>
        <record_locator>4294993825</record_locator>
        <supplier_conf_num>CN10001005</supplier_conf_num>
        <supplier_contact></supplier_contact>
        <supplier_email_address></supplier_email_address>
        <supplier_name></supplier_name>
        <supplier_phone></supplier_phone>
        <supplier_url></supplier_url>
        <is_purchased>1</is_purchased>
        <notes></notes>
        <restrictions></restrictions>
        <total_cost></total_cost>
        <Segment>
            <StartDateTime>
                <date>2013-08-21</date>
                <time>07:45:00</time>
            </StartDateTime>
            <EndDateTime>
                <date>2013-08-21</date>
                <time>13:03:00</time>
            </EndDateTime>
            <start_airport_code>PHX</start_airport_code>
            <start_gate>A11</start_gate>
            <start_terminal>4</start_terminal>
            <end_airport_code>ORD</end_airport_code>
            <end_gate>F8</end_gate>
            <end_terminal>2</end_terminal>
            <marketing_airline>US</marketing_airline>
            <marketing_flight_number>1</marketing_flight_number>
            <aircraft>320</aircraft>
            <duration></duration>
            <distance>1433</distance>
            <notes></notes>
            <seats></seats>
            <service_class>Economy</service_class>
            <stops>Nonstop</stops>
        </Segment>
        <Segment>
            <StartDateTime>
                <date>2013-08-24</date>
                <time>13:55:00</time>
            </StartDateTime>
            <EndDateTime>
                <date>2013-08-24</date>
                <time>16:58:00</time>
            </EndDateTime>
            <start_airport_code>ORD</start_airport_code>
            <start_gate></start_gate>
            <start_terminal></start_terminal>
            <end_airport_code>PHX</end_airport_code>
            <end_gate></end_gate>
            <end_terminal></end_terminal>
            <marketing_airline>US</marketing_airline>
            <marketing_flight_number>1728</marketing_flight_number>
            <aircraft>A320</aircraft>
            <duration></duration>
            <distance></distance>
            <notes></notes>
            <seats></seats>
            <service_class>Economy</service_class>
            <stops> stops</stops>
        </Segment>
        <Traveler>
            <first_name>William</first_name>
            <middle_name></middle_name>
            <last_name>Never</last_name>
            <frequent_traveler_num></frequent_traveler_num>
            <frequent_traveler_supplier></frequent_traveler_supplier>
            <ticket_num></ticket_num>
        </Traveler>
    </AirObject>
</Response>  

Create a New Trip

This endpoint is used for creating a new trip. To create a new trip, the specified dates in the content body can only span the trip to be created and cannot span an existing trip. To create or update a trip on behalf of a user, the OAuth access token used to make the API call should be associated with the SAP Concur account of that user. The TripLink supplier or TMC must be registered with SAP Concur and have an SAP Concur account that has one of the following user roles: Web Services Administrator for Professional, or Can Administer for Standard.

Request

POST /travel/trip/v1.1?[userid_type=login&user_id=login_ID]

Request Parameters

Parameter Name Data Type Description
userid_type string Optional: The type of user identification to use. Possible value is: login_id.
userid_value string Optional: The value for the user identification type. Currently the only available type is login_id so the value is the login credentials. This parameter must be provided in conjunction with the userid_type parameter. The userid_type and userid_value parameters can only be used if the user account associated with the OAuth 2.0 access token is associated with an SAP Concur account with one of these roles: Web Services Administrator for Professional or Can Administer for Standard. The format for the request URI using the userid_type and userid_value query parameters is /travel/trip/v1.1/trip_ID?userid_type=login&userid_value=login_ID.

Headers

Authorization Header (required)

Authorization: OAuth {access_token}

Where access_token is the OAuth 2.0 access token of the user whose trip you want to create or update. If you want to access company-wide itinerary information, the user account associated with the OAuth 2.0 access token must have an SAP Concur account with one of these roles: Web Services Administrator for Professional or Can Administer for Standard.

Create New Trip Request Schema

Element Name Required or Optional TripLink Data Type Description
Itinerary required Y ItineraryType The root element for a trip. For this endpoint, it contains the following elements: ClientLocator, ItinSourceName, TripName, Comments, StartDateLocal, EndDateLocal, BookedByFirstName, BookedByLastName, Bookings.
TripName required Y string Name of the trip. Maximum length: 255 characters.
TripStatus required Y unsignedByte The status of the trip. One of the following: 0 - Confirmed; 1 - Ticketed; 2 - Canceled; 6 - Proposal; 7 - Booked Proposal. This element only appears if the includeCanceledTrips query parameter is used in the request.
RecordLocator required Y string The unique identifier for a booking. This is often six alphanumeric characters, but can have other formats depending on the booking source.
BookingSource required Y string The name of the booking source for this booking. A booking source is a textual name the system uses to track where a booking took place. This could be a GDS, OTA, Vendor code for a Supplier website, or Supplier Direct Connect API. For TripLink suppliers, this is the supplier's name.
StartDateLocal optional Y dateTime The start date of the trip in the starting location’s timezone. Format: YYYY-MM-DDThh:mm:ss.
EndDateLocal optional Y dateTime The end date of the trip in the ending location’s timezone. Format: YYYY-MM-DDThh:mm:ss.
BookedByFirstName optional Y string The first name of the person who booked the trip.
BookedByLastName optional Y string The last name of the person who booked the trip.
Bookings optional Y array A parent element that contains a Booking child element for each booking associated with this itinerary.
Booking optional Y array A child element of the Bookings element which in turn contains the following child elements: Segments, Passengers, RecordLocator, BookingSource, DateModifiedUtc, DateBookedLocal, ItinSourceName, and PassengerCount.
Segments optional Y array List of segments in this booking. The child elements included in this element vary depending on whether a TMC, client, third-party developer, or TripLink supplier is requesting the itinerary details: For TMCs, clients, and third-party developers, the Segments element contains one or more Air, Car, Hotel, Dining, Ride, Rail, Parking, or Travel parent elements. For TripLink suppliers, the Segments element contains one or more Air, Car, Hotel, or Ride parent elements.
Comments optional Y string Comments for the itinerary. Maximum length: 512 characters.
ItinSourceName optional N string The itinerary source. Format: TravelSupplier.
BookingOwner optional Y string Indicates the tool that supplied the booking to Concur Travel.
Source optional N/A string This element is obsolete. It is supported for backward compatibility only.
DateBookedLocal optional Y dateTime The date the booking was created, in the booking location's local time. Format: YYYY-MM-DDThh:mm:ss.
FormOfPaymentName optional - string The name of the form of payment for the booking.
FormOfPaymentType optional - string The type of the form of payment.
TicketMailingAddress optional - - The mailing address for the booked ticket, if available.
TicketPickupLocation optional - - The pickup location for the booked ticket, if available.
TicketPickupNumber optional - - The confirmation number for the booked ticket, if available.
AirfareQuotes optional - array List of stored airfare quotes for this booking.
Airline Tickets optional - array List of airline tickets for this booking.
Charges optional - array List of charges for this booking.
MiscChargeOrders optional - array List of miscellaneous air charges for this booking.
Passengers optional Y array Contains a Passenger child element for each included passenger. The Passenger child element in turn contains the following required child elements: NameFirst, NameLast, and the following optional elements: NameMiddle, NamePrefix, NameRemark, NameSuffix, NameTitle, TextName, and FrequentTravelerProgram.
PassPrograms optional - array List of pass programs for this booking. This parent element has a PassProgram child element for each pass program associated with the booking. The PassProgram parent element has the following child elements: Amount, Name, Type, UserFirstName, and UserLastname.
PhoneNumbers optional - array List of phone numbers associated with this booking. This parent element has a PhoneNumberData child element for each phone number associated with the booking. The PhoneNumberData parent element has the following child elements: PassengerRPH, PhoneNumber, Type, and Description.
RailPayments optional - array List of rail payments associated with rail segments in this booking. It has the following child elements: RailPayment that represents the payment information for a rail booking and RailAdjustment for the amount adjusted for a rail booking.
Segments optional Y array List of segments in this booking. The child elements included in this element vary depending on whether a TMC, client, third-party developer, or TripLink supplier is requesting the itinerary details: For TMCs, clients, and third-party developers, the Segments element contains one or more Air, Car, Hotel, Dining, Ride, Rail, Parking, or Travel parent elements. For TripLink suppliers, the Segments element contains one or more Air, Car, Hotel, or Ride parent elements.
Delivery optional - - The method this booking was delivered.
WaitListSegments optional - - The segments that the traveler is waitlisted for this booking.
Warning optional - - The warnings associated with the booking.
WebAddresses optional - - List of web addresses such as emails, pick-up URLs, and so on associated with this booking.

Create New Trip Response Schema

The response returns an HTTP status code and if the trip is created successfully, it also returns the full posted trip details with the following additional elements inside the Itinerary parent element:

Element Name Data Type TripLink Description
id string Y The URI including the trip ID.
ItinLocator string Y The Itinerary Locator value (trip ID without the URL). The ItinLocator value is used when updating an existing trip.
DateModifiedUtc dateTime Y The UTC formatted date that this booking was last modified.
BookedVia string Y The booking method or the GDS the itinerary was booked in.
DateBookedLocal dateTime Y The date, in the traveler’s local time, that the booking was made.

Examples

Example 1: TMC Creates a Trip for User Using Their Login Credentials

This example shows how to create a trip for a user using their login credentials.

Request

POST /api/travel/trip/v1.1?userid_type=login_id&userid_value=cm@example.com HTTPS/1.1
Host: www.concursolutions.com
Authorization: OAuth {access token}
Content-Type: application/xml
...

<Itinerary xmlns="http://www.concursolutions.com/api/travel/trip/2010/06">
    <ClientLocator>KK-CNQ-1M1P6-5HJ</ClientLocator>
    <ItinSourceName>ConcurConnectAPI</ItinSourceName>
    <TripName>Trip from Dallas to Seattle</TripName>
    <Comments />
    <StartDateLocal>2013-12-21T07:25:00</StartDateLocal>
    <EndDateLocal>2013-12-24T23:59:00</EndDateLocal>
    <BookedByFirstName>Chris</BookedByFirstName>
    <BookedByLastName>Miller</BookedByLastName>
    <Bookings>
        <Booking>
            <Segments>
                <Car>
                    <Vendor>CQ</Vendor>
                    <Status>HK</Status>
                    <StartDateLocal>2013-12-21T12:00:00</StartDateLocal>
                    <EndDateLocal>2013-12-24T12:00:00</EndDateLocal>
                    <ConfirmationNumber>F1672664579</ConfirmationNumber>
                    <StartCityCode>SEA</StartCityCode>
                    <EndCityCode>SEA</EndCityCode>
                    <StartLocation>SEA</StartLocation>
                    <EndLocation>SEA</EndLocation>
                    <Class>E</Class>
                    <Body>C</Body>
                    <Transmission>M</Transmission>
                    <AirCondition>R</AirCondition>
                    <NumCars>1</NumCars>
                    <DiscountCode>346660</DiscountCode>
                    <DailyRate>44.0000</DailyRate>
                    <TotalRate>44.0000</TotalRate>
                    <RateType>D</RateType>
                    <Currency>USD</Currency>
                    <Charges>
                        <Fixed>
                            <Description>Dropoff Fee</Description>
                            <Currency>USD</Currency>
                            <Amount>0.0000</Amount>
                            <IsPrimary>false</IsPrimary>
                            <SemanticsCode>DROPOFFFEE</SemanticsCode>
                            <SemanticsVendorType>C</SemanticsVendorType>
                        </Fixed>
                        <RateWithAllowance>
                            <Currency>USD</Currency>
                            <Amount>44.0000</Amount>
                            <StartDateLocal>2013-12-21T12:00:00</StartDateLocal>
                            <IsPrimary>true</IsPrimary>
                            <SemanticsCode>DAYS</SemanticsCode>
                            <SemanticsVendorType>C</SemanticsVendorType>
                            <PerUnit>DAY</PerUnit>
                            <NumUnits>1.0000</NumUnits>
                            <AllowanceNumUnits>250.0000</AllowanceNumUnits>
                            <AllowanceAmount>0.2400</AllowanceAmount>
                            <AllowanceIsUnlimited>false</AllowanceIsUnlimited>
                        </RateWithAllowance>
                    </Charges>
                </Car>
            </Segments>
            <Passengers>
                <Passenger>
                    <NameFirst>Chris</NameFirst>
                    <NameLast>Miller</NameLast>
                </Passenger>
            </Passengers>
            <RecordLocator>C123456789</RecordLocator>
            <BookingSource>TravelBookings.com</BookingSource>
            <DateBookedLocal>2013-11-10T13:01:00</DateBookedLocal>
            <ItinSourceName>ConcurConnectAPI</ItinSourceName>
            <PassengerCount>1</PassengerCount>
        </Booking>
        <Booking>
            <Segments>
                <Hotel>
                    <Vendor>CQ</Vendor>
                    <Status>GK</Status>
                    <StartDateLocal>2013-12-21T23:59:00</StartDateLocal>
                    <EndDateLocal>2013-12-24T23:59:00</EndDateLocal>
                    <ConfirmationNumber>3364214265</ConfirmationNumber>
                    <RateCode>LV4</RateCode>
                    <Name>CONCUR HOTEL</Name>
                    <HotelPropertyId>CONQ</HotelPropertyId>
                    <CheckinTime>03:00 PM</CheckinTime>
                    <CheckoutTime>12:00 PM</CheckoutTime>
                    <NumPersons>1</NumPersons>
                    <NumRooms>1</NumRooms>
                    <CancellationPolicy>Cxl 1 day prior to Arrival</CancellationPolicy>
                    <DailyRate>240.3500</DailyRate>
                    <Currency>USD</Currency>
                    <RoomDescription>1 KING BED ACCESSIBLE ROOM - K1RRC</RoomDescription>
                    <Charges>
                        <Rate>
                            <Currency>USD</Currency>
                            <Amount>240.3500</Amount>
                            <StartDateLocal>2013-12-21T23:59:00</StartDateLocal>
                            <IsPrimary>false</IsPrimary>
                            <SemanticsCode>ROOMRATE</SemanticsCode>
                            <SemanticsVendorType>H</SemanticsVendorType>
                            <PerUnit>DAY</PerUnit>
                            <NumUnits>3.0000</NumUnits>
                        </Rate>
                    </Charges>
                </Hotel>
            </Segments>
            <Passengers>
                <Passenger>
                    <NameFirst>Chris</NameFirst>
                    <NameLast>Miller</NameLast>
                </Passenger>
            </Passengers>
            <RecordLocator>0987654321</RecordLocator>
            <BookingSource>TravelBookings.com</BookingSource>
            <DateBookedLocal>2013-11-10T13:01:00</DateBookedLocal>
            <OriginalItinLocator>33491211</OriginalItinLocator>
            <ItinSourceName>ConcurConnectAPI</ItinSourceName>
            <PassengerCount>1</PassengerCount>
        </Booking>
    </Bookings>
</Itinerary>

Response

<Itinerary xmlns="http://www.concursolutions.com/api/travel/trip/2010/06">
    <id>https://www.concursolutions.com/api/travel/trip/v1.1/CNQR1234567890</id>
    <ItinLocator>CNQR1234567890</ItinLocator>
    <ClientLocator>KK-CNQ-1M1P6-5HJ</ClientLocator>
    <ItinSourceName>ConcurTravel</ItinSourceName>
    <TripName>Trip from Dallas to Seattle</TripName>
    <Comments />
    <StartDateLocal>2013-12-21T07:25:00</StartDateLocal>
    <EndDateLocal>2013-12-24T23:59:00</EndDateLocal>
    <DateModifiedUtc>2012-07-24T19:15:52</DateModifiedUtc>
    <BookedVia>EveryGDS</BookedVia>
    <BookedByFirstName>Chris</BookedByFirstName>
    <BookedByLastName>Miller</BookedByLastName>
    <DateBookedLocal>2012-07-24T19:15:52</DateBookedLocal>
    <Bookings>
        <Booking>
            <Segments>
                <Car>
                    <Vendor>CQ</Vendor>
                    <Status>HK</Status>
                    <StartDateLocal>2013-12-21T12:00:00</StartDateLocal>
                    <EndDateLocal>2013-12-24T12:00:00</EndDateLocal>
                    <ConfirmationNumber>F1672664579</ConfirmationNumber>
                    <DateModifiedUtc>2012-07-24T19:15:52</DateModifiedUtc>
                    <StartCityCode>SEA</StartCityCode>
                    <EndCityCode>SEA</EndCityCode>
                    <StartLocation>SEA</StartLocation>
                    <EndLocation>SEA</EndLocation>
                    <Class>E</Class>
                    <Body>C</Body>
                    <Transmission>M</Transmission>
                    <AirCondition>R</AirCondition>
                    <NumCars>1</NumCars>
                    <DiscountCode>346660</DiscountCode>
                    <DailyRate>44.0000</DailyRate>
                    <TotalRate>44.0000</TotalRate>
                    <RateType>D</RateType>
                    <Currency>USD</Currency>
                    <Charges>
                        <Fixed>
                            <Description>Dropoff Fee</Description>
                            <Currency>USD</Currency>
                            <Amount>0.0000</Amount>
                            <IsPrimary>false</IsPrimary>
                            <SemanticsCode>DROPOFFFEE</SemanticsCode>
                            <SemanticsVendorType>C</SemanticsVendorType>
                        </Fixed>
                        <RateWithAllowance>
                            <Currency>USD</Currency>
                            <Amount>44.0000</Amount>
                            <StartDateLocal>2013-12-21T12:00:00</StartDateLocal>
                            <IsPrimary>true</IsPrimary>
                            <SemanticsCode>DAYS</SemanticsCode>
                            <SemanticsVendorType>C</SemanticsVendorType>
                            <PerUnit>DAY</PerUnit>
                            <NumUnits>1.0000</NumUnits>
                            <AllowanceNumUnits>250.0000</AllowanceNumUnits>
                            <AllowanceAmount>0.2400</AllowanceAmount>
                            <AllowanceIsUnlimited>false</AllowanceIsUnlimited>
                        </RateWithAllowance>
                    </Charges>
                </Car>
            </Segments>
            <Passengers>
                <Passenger>
                    <NameFirst>Chris</NameFirst>
                    <NameLast>Miller</NameLast>
                </Passenger>
            </Passengers>
            <RecordLocator>C123456789</RecordLocator>
            <BookingSource>ConcurCars</BookingSource>
            <DateModifiedUtc>2012-07-24T19:15:52</DateModifiedUtc>
            <DateBookedLocal>2013-11-10T13:01:00</DateBookedLocal>
            <ItinSourceName>TravelSupplier</ItinSourceName>
            <PassengerCount>1</PassengerCount>
        </Booking>
        <Booking>
            <Segments>
                <Hotel>
                    <Vendor>CQ</Vendor>
                    <Status>GK</Status>
                    <StartDateLocal>2013-12-21T23:59:00</StartDateLocal>
                    <EndDateLocal>2013-12-24T23:59:00</EndDateLocal>
                    <ConfirmationNumber>3364214265</ConfirmationNumber>
                    <DateModifiedUtc>2012-07-24T19:15:52</DateModifiedUtc>
                    <RateCode>LV4</RateCode>
                    <Name>CONCUR HOTEL</Name>
                    <HotelPropertyId>CONQ</HotelPropertyId>
                    <CheckinTime>00:00</CheckinTime>
                    <CheckoutTime>00:00</CheckoutTime>
                    <NumPersons>1</NumPersons>
                    <NumRooms>1</NumRooms>
                    <CancellationPolicy>Cxl 1 day prior to Arrival</CancellationPolicy>
                    <DailyRate>240.3500</DailyRate>
                    <Currency>USD</Currency>
                    <RoomDescription>1 KING BED ACCESSIBLE ROOM - K1RRC</RoomDescription>
                    <Charges>
                        <Rate>
                            <Currency>USD</Currency>
                            <Amount>240.3500</Amount>
                            <StartDateLocal>2013-12-21T23:59:00</StartDateLocal>
                            <IsPrimary>false</IsPrimary>
                            <SemanticsCode>ROOMRATE</SemanticsCode>
                            <SemanticsVendorType>H</SemanticsVendorType>
                            <PerUnit>DAY</PerUnit>
                            <NumUnits>3.0000</NumUnits>
                        </Rate>
                    </Charges>
                </Hotel>
            </Segments>
            <Passengers>
                <Passenger>
                    <NameFirst>Chris</NameFirst>
                    <NameLast>Miller</NameLast>
                </Passenger>
            </Passengers>
            <RecordLocator>0987654321</RecordLocator>
            <BookingSource>ConcurHotel</BookingSource>
            <DateModifiedUtc>2012-07-24T19:15:52</DateModifiedUtc>
            <DateBookedLocal>2013-11-10T13:01:00</DateBookedLocal>
            <OriginalItinLocator>33491211</OriginalItinLocator>
            <ItinSourceName>ConcurTravel</ItinSourceName>
            <PassengerCount>1</PassengerCount>
        </Booking>
    </Bookings>
</Itinerary>

This example shows how a TripLink supplier creates a trip.

Request

POST /api/travel/trip/v1.1/ HTTPS/1.1
Host: www.concursolutions.com
Authorization: OAuth {access token}
Content-Type: application/xml
...

<Itinerary xmlns="http://www.concursolutions.com/api/travel/trip/2010/06">
    <TripName>Trip from Dallas to Seattle</TripName>
    <TripStatus>HK</TripStatus>
    <Comments />
    <StartDateLocal>2013-12-21T07:25:00</StartDateLocal>
    <EndDateLocal>2013-12-24T23:59:00</EndDateLocal>
    <BookedByFirstName>Chris</BookedByFirstName>
    <BookedByLastName>Miller</BookedByLastName>
    <Bookings>
        <Booking>
            <Segments>
                <Car>
                    <StartDateLocal>2013-12-21T12:00:00</StartDateLocal>
                    <EndDateLocal>2013-12-24T12:00:00</EndDateLocal>
                    <StartCityCode>SEA</StartCityCode>
                    <EndCityCode>SEA</EndCityCode>
                </Car>
            </Segments>
            <Passengers>
                <Passenger>
                    <NameFirst>Chris</NameFirst>
                    <NameLast>Miller</NameLast>
                </Passenger>
            </Passengers>
            <RecordLocator>C123456789</RecordLocator>
            <BookingSource>TravelBookings.com</BookingSource>
            <DateBookedLocal>2013-11-10T13:01:00</DateBookedLocal>
        </Booking>
        <Booking>
            <Segments>
                <Hotel>
                    <Status>GK</Status>
                    <StartCityCode>SEA</StartCityCode>
                    <StartDateLocal>2013-12-21T23:59:00</StartDateLocal>
                    <EndDateLocal>2013-12-24T23:59:00</EndDateLocal>
                    <TimeZoneId>Pacific</TimeZoneId>
                    <DateModifiedUtc>2012-07-24T19:15:52</DateModifiedUtc>
                    <StartCity>Seattle</StartCity>
                    <StartCountry>US</StartCountry>
                </Hotel>
            </Segments>
            <Passengers>
                <Passenger>
                    <NameFirst>Chris</NameFirst>
                    <NameLast>Miller</NameLast>
                </Passenger>
            </Passengers>
            <RecordLocator>0987654321</RecordLocator>
            <BookingSource>TravelBookings.com</BookingSource>
            <DateBookedLocal>2013-11-10T13:01:00</DateBookedLocal>
        </Booking>
    </Bookings>
</Itinerary>

Response

<Itinerary xmlns="http://www.concursolutions.com/api/travel/trip/2010/06">
    <id>https://www.concursolutions.com/api/travel/trip/v1.1/CNQR1234567890</id>
    <ItinLocator>CNQR1234567890</ItinLocator>
    <TripName>Trip from Dallas to Seattle</TripName>
    <TripStatus>HK</TripStatus>
    <Comments />
    <StartDateLocal>2013-12-21T07:25:00</StartDateLocal>
    <EndDateLocal>2013-12-24T23:59:00</EndDateLocal>
    <DateModifiedUtc>2012-07-24T19:15:52</DateModifiedUtc>
    <BookedVia>EveryGDS</BookedVia>
    <BookedByFirstName>Chris</BookedByFirstName>
    <BookedByLastName>Miller</BookedByLastName>
    <DateBookedLocal>2012-07-24T19:15:52</DateBookedLocal>
    <Bookings>
        <Booking>
            <Segments>
                <Car>
                    <StartDateLocal>2013-12-21T12:00:00</StartDateLocal>
                    <EndDateLocal>2013-12-24T12:00:00</EndDateLocal>
                    <StartCityCode>SEA</StartCityCode>
                    <EndCityCode>SEA</EndCityCode>
                </Car>
            </Segments>
            <Passengers>
                <Passenger>
                    <NameFirst>Chris</NameFirst>
                    <NameLast>Miller</NameLast>
                </Passenger>
            </Passengers>
            <RecordLocator>C123456789</RecordLocator>
            <BookingSource>TravelBookings.com</BookingSource>
            <DateBookedLocal>2013-11-10T13:01:00</DateBookedLocal>
        </Booking>
        <Booking>
            <Segments>
                <Hotel>
                    <Status>GK</Status>
                    <StartCityCode>SEA</StartCityCode>
                    <StartDateLocal>2013-12-21T23:59:00</StartDateLocal>
                    <EndDateLocal>2013-12-24T23:59:00</EndDateLocal>
                    <TimeZoneId>Pacific</TimeZoneId>
                    <DateModifiedUtc>2012-07-24T19:15:52</DateModifiedUtc>
                    <StartCity>Seattle</StartCity>
                    <StartCountry>US</StartCountry>
                </Hotel>
            </Segments>
            <Passengers>
                <Passenger>
                    <NameFirst>Chris</NameFirst>
                    <NameLast>Miller</NameLast>
                </Passenger>
            </Passengers>
            <RecordLocator>0987654321</RecordLocator>
            <BookingSource>TravelBookings.com</BookingSource>
            <DateBookedLocal>2013-11-10T13:01:00</DateBookedLocal>
        </Booking>
    </Bookings>
</Itinerary>

Example 3: Third-Party Developer Creates a Trip Using the Access Token Used to Make the API Call

This example shows how to create a trip for a user whose account is associated with the access token used to make the API call.

Request

POST https://www.concursolutions.com/api/travel/trip/v1.1 HTTPS/1.1
Authorization: OAuth {access token}
Content-Type: application/xml
...

<Itinerary xmlns="http://www.concursolutions.com/api/travel/trip/2010/06">
    <ClientLocator>KK-CNQ-1M1P6-5HJ</ClientLocator>
    <ItinSourceName>ConcurConnectAPI</ItinSourceName>
    <TripName>Trip from Dallas to Seattle</TripName>
    <Comments />
    <StartDateLocal>2013-12-21T07:25:00</StartDateLocal>
    <EndDateLocal>2013-12-24T23:59:00</EndDateLocal>
    <BookedByFirstName>Chris</BookedByFirstName>
    <BookedByLastName>Miller</BookedByLastName>
    <TripStatus>7</TripStatus>
    <TravelRequestId>3339</TravelRequestId>
    <CustomAttributes>
        <CustomAttribute>
            <ExternalId />
            <DataType>Numeric</DataType>
            <Name>ProposalBatchSize</Name>
            <DisplayTitle />
            <Data>3</Data>
            <DisplayOnItinerary>true</DisplayOnItinerary>
        </CustomAttribute>
        <CustomAttribute>
            <ExternalId />
            <DataType>Numeric</DataType>
            <Name>ProposalSequenceIndex</Name>
            <DisplayTitle />
            <Data>1</Data>
            <DisplayOnItinerary>true</DisplayOnItinerary>
        </CustomAttribute>
    </CustomAttributes>
    <Bookings>
        <Booking>
            <Segments>
                <Car>
                    <Vendor>CQ</Vendor>
                    <Status>HK</Status>
                    <StartDateLocal>2013-12-21T12:00:00</StartDateLocal>
                    <EndDateLocal>2013-12-24T12:00:00</EndDateLocal>
                    <ConfirmationNumber>F1672664579</ConfirmationNumber>
                    <StartCityCode>SEA</StartCityCode>
                    <EndCityCode>SEA</EndCityCode>
                    <StartLocation>SEA</StartLocation>
                    <EndLocation>SEA</EndLocation>
                    <Class>E</Class>
                    <Body>C</Body>
                    <Transmission>M</Transmission>
                    <AirCondition>R</AirCondition>
                    <NumCars>1</NumCars>
                    <DiscountCode>346660</DiscountCode>
                    <DailyRate>44.0000</DailyRate>
                    <TotalRate>44.0000</TotalRate>
                    <RateType>D</RateType>
                    <Currency>USD</Currency>
                    <Charges>
                        <Fixed>
                            <Description>Dropoff Fee</Description>
                            <Currency>USD</Currency>
                            <Amount>0.0000</Amount>
                            <IsPrimary>false</IsPrimary>
                            <SemanticsCode>DROPOFFFEE</SemanticsCode>
                            <SemanticsVendorType>C</SemanticsVendorType>
                        </Fixed>
                        <RateWithAllowance>
                            <Currency>USD</Currency>
                            <Amount>44.0000</Amount>
                            <StartDateLocal>2013-12-21T12:00:00</StartDateLocal>
                            <IsPrimary>true</IsPrimary>
                            <SemanticsCode>DAYS</SemanticsCode>
                            <SemanticsVendorType>C</SemanticsVendorType>
                            <PerUnit>DAY</PerUnit>
                            <NumUnits>1.0000</NumUnits>
                            <AllowanceNumUnits>250.0000</AllowanceNumUnits>
                            <AllowanceAmount>0.2400</AllowanceAmount>
                            <AllowanceIsUnlimited>false</AllowanceIsUnlimited>
                        </RateWithAllowance>
                    </Charges>
                </Car>
            </Segments>
            <Passengers>
                <Passenger>
                    <NameFirst>Chris</NameFirst>
                    <NameLast>Miller</NameLast>
                </Passenger>
            </Passengers>
            <RecordLocator>C123456789</RecordLocator>
            <BookingSource>TravelBookings.com</BookingSource>
            <DateBookedLocal>2013-11-10T13:01:00</DateBookedLocal>
            <ItinSourceName>ConcurConnectAPI</ItinSourceName>
            <PassengerCount>1</PassengerCount>
        </Booking>
        <Booking>
            <Segments>
                <Hotel>
                    <Vendor>CQ</Vendor>
                    <Status>GK</Status>
                    <StartDateLocal>2013-12-21T23:59:00</StartDateLocal>
                    <EndDateLocal>2013-12-24T23:59:00</EndDateLocal>
                    <ConfirmationNumber>3364214265</ConfirmationNumber>
                    <RateCode>LV4</RateCode>
                    <Name>CONCUR HOTEL</Name>
                    <HotelPropertyId>CONQ</HotelPropertyId>
                    <CheckinTime>03:00 PM</CheckinTime>
                    <CheckoutTime>12:00 PM</CheckoutTime>
                    <NumPersons>1</NumPersons>
                    <NumRooms>1</NumRooms>
                    <CancellationPolicy>Cxl 1 day prior to Arrival</CancellationPolicy>
                    <DailyRate>240.3500</DailyRate>
                    <Currency>USD</Currency>
                    <RoomDescription>1 KING BED ACCESSIBLE ROOM - K1RRC</RoomDescription>
                    <Charges>
                        <Rate>
                            <Currency>USD</Currency>
                            <Amount>240.3500</Amount>
                            <StartDateLocal>2013-12-21T23:59:00</StartDateLocal>
                            <IsPrimary>false</IsPrimary>
                            <SemanticsCode>ROOMRATE</SemanticsCode>
                            <SemanticsVendorType>H</SemanticsVendorType>
                            <PerUnit>DAY</PerUnit>
                            <NumUnits>3.0000</NumUnits>
                        </Rate>
                    </Charges>
                </Hotel>
            </Segments>
            <Passengers>
                <Passenger>
                    <NameFirst>Chris</NameFirst>
                    <NameLast>Miller</NameLast>
                </Passenger>
            </Passengers>
            <RecordLocator>0987654321</RecordLocator>
            <BookingSource>TravelBookings.com</BookingSource>
            <DateBookedLocal>2013-11-10T13:01:00</DateBookedLocal>
            <OriginalItinLocator>33491211</OriginalItinLocator>
            <ItinSourceName>ConcurConnectAPI</ItinSourceName>
            <PassengerCount>1</PassengerCount>
        </Booking>
    </Bookings>
</Itinerary>

Response

The response is the same as in Example 1.

Update a Trip

Creates a new trip or updates an existing trip. A new trip will be created if the trip dates span no existing trip and the request doesn’t include a tripId. If a tripId is included in the URI it will update the specified trip. The full trip information is included in the update request, which replaces the existing trip.

This endpoint can be used to create trips for a user that is not the OAuth consumer. This is most often done when a travel supplier or TMC needs to create a trip on behalf of a user. The supplier or TMC must be registered with SAP Concur and have an SAP Concur account that has one of the following user roles: Web Services Administrator for Professional, or Can Administer for Standard.

Cancel a Trip

This endpoint can be used to cancel all segments in a trip. To cancel a trip on behalf of a user, the OAuth access token used to make the API call should be associated with the SAP Concur account of that user. The TripLink supplier or TMC must be registered with SAP Concur and have an SAP Concur account that has one of the following user roles: Web Services Administrator for Professional, or Can Administer for Standard.

Request

POST /travel/trip/v1.1/cancel?tripid=trip_ID[&userid_type=login&userid_value=login_ID]

Path Parameters

Parameter Name Data Type Description
cancel required string

Request Parameters

Parameter Name Data Type Description
tripid string Optional: The identifier for the trip to be updated. For example, if the value of tripid is I2uwiJJw8r7Owl3IWlSie9WIelxhAhwiL, then the request is POST /travel/trip/v1.1?tripid=I2uwiJJw8r7Owl3IWlSie9WIelxhAhwiL.
userid_type string Optional: The type of user identification to use. Possible value is: login_id.
userid_value string Optional: The user's login ID. This parameter must be provided in conjunction with the userid_type parameter. The userid_type and userid_value parameters can only be used if the user account associated with the OAuth 2.0 access token must have an SAP Concur account with one of these roles: Web Services Administrator for Professional or Can Administer for Standard. The format for the request URI using the userid_type and userid_value query parameters is /travel/trip/v1.1/trip_ID?userid_type=login&userid_value=login_ID.

Headers

Authorization Header (Required)

Authorization: OAuth {access_token}

Where access_token is the OAuth 2.0 access token of the user whose trip you want to create or update. If you want to access company-wide itinerary information, the user account associated with the OAuth 2.0 access token must have an SAP Concur account with one of these roles: Web Services Administrator for Professional or Can Administer for Standard.

Request Content Body

None.

Cancel Trip Request Schema

The request returns the full trip details for the cancelled trip. If the request is successful, the response trip will not contain any segments because they have been cancelled. The response includes the following additional elements inside the Itinerary parent element:

Parameter Name Data Type Description
id string The URI including the trip ID.
ItinLocator string The itinerary locator value (trip ID without the URL). The ItinLocator value is used when updating an existing trip.
DateModifiedUtc dateTime The UTC formatted date that this booking was last modified.
BookedVia string The GDS the itinerary was booked in.
DateBookedLocal dateTime The date, in the traveler’s local time, that the booking was made.

Examples

Example: Cancel a Trip with a Specific Trip ID

Request

POST /api/travel/trip/v1.1/cancel?tripId=CNQR1234567890 HTTPS/1.1
Host: www.concursolutions.com
Authorization: OAuth {access token}
...

Response

<Itinerary xmlns="http://www.concursolutions.com/api/travel/trip/2010/06">
    <id>https://www.concursolutions.com/api/travel/trip/v1.1/CNQR1234567890</id>
    <ItinLocator>CNQR1234567890</ItinLocator>
    <ClientLocator>KK-CNQ-1M1P6-5HJ</ClientLocator>
    <ItinSourceName>ConcurTravel</ItinSourceName>
    <TripName>Trip from Dallas to Seattle</TripName>
    <Comments />
    <StartDateLocal>2013-12-21T07:25:00</StartDateLocal>
    <EndDateLocal>2013-12-24T23:59:00</EndDateLocal>
    <DateModifiedUtc>2012-07-24T19:15:52</DateModifiedUtc>
    <BookedVia>EveryGDS</BookedVia>
    <BookedByFirstName>Chris</BookedByFirstName>
    <BookedByLastName>Miller</BookedByLastName>
    <DateBookedLocal>2012-07-24T19:15:52</DateBookedLocal>
    <Bookings>
        <Booking>
            <Segments/>
            <Passengers>
                <Passenger>
                    <NameFirst>Chris</NameFirst>
                    <NameLast>Miller</NameLast>
                </Passenger>
            </Passengers>
            <RecordLocator>C123456789</RecordLocator>
            <BookingSource>ConcurCars</BookingSource>
            <DateModifiedUtc>2012-07-24T19:15:52</DateModifiedUtc>
            <DateBookedLocal>2013-11-10T13:01:00</DateBookedLocal>
            <ItinSourceName>TravelSupplier</ItinSourceName>
            <PassengerCount>1</PassengerCount>
        </Booking>
        <Booking>
            <Segments/>
            <Passengers>
                <Passenger>
                    <NameFirst>Chris</NameFirst>
                    <NameLast>Miller</NameLast>
                </Passenger>
            </Passengers>
            <RecordLocator>0987654321</RecordLocator>
            <BookingSource>ConcurHotel</BookingSource>
            <DateModifiedUtc>2012-07-24T19:15:52</DateModifiedUtc>
            <DateBookedLocal>2013-11-10T13:01:00</DateBookedLocal>
            <OriginalItinLocator>33491211</OriginalItinLocator>
            <ItinSourceName>ConcurTravel</ItinSourceName>
            <PassengerCount>1</PassengerCount>
        </Booking>
    </Bookings>
</Itinerary>

Booking Endpoint

The Booking resource represents booking segments in the SAP Concur Travel system. TripLink suppliers use this resource to display a subset of the full booking fields.

Version

Version 1.1

URI

/travel/booking/v1.1/{query_parameters}

Scope

In order to obtain itinerary data when making Itinerary API calls, the value of the OAuth scope parameter must be set to: ITINER

Create or Update Booking

Creates a new booking or updates an existing booking. A new booking will be assigned to the specified trip, or if no trip is specified, the first itinerary that spans the booking dates. If no trip is specified and no itinerary exists that spans the booking dates, a new itinerary will be created.

This endpoint can be used to create/update bookings for a user that is not the OAuth consumer. This is most often done when a travel supplier or Travel Management Company needs to create/update a booking on behalf of a user. The supplier or TMC must be registered with SAP Concur, and must have an account that has one of the following user roles: Web Services Administrator for Professional, or Can Administer for Standard.

Request

POST /api/travel/booking/v1.0?tripId=12345678 HTTPS/1.1
Host: www.concursolutions.com
Authorization: OAuth {access token}

Request Parameters

Query Parameters - Optional

Examples:

https://www.concursolutions.com/api/travel/booking/v1.1?tripId={tripId}

https://www.concursolutions.com/api/travel/booking/v1.1?userid_type=login_id&userid_value={loginID}

Content Type

application/xml

Authorization Header

Authorization header with OAuth token for a valid SAP Concur user. In order to create or update booking for anyone other than the OAuth consumer, the OAuth consumer must have one of the following user roles in SAP Concur: Company Administrator or Web Services Administrator for Professional, or Can Administer for Standard.

Create or Update Booking Request Schema

The request contains a Booking parent element with the following child elements:

Required Element Description
BookingSource The supplier's name.
RecordLocator Record locator for this booking. This is often six alphanumeric characters but can have other formats depending on the booking source
Optional Element Description
DateBookedLocal The date the booking was created, in the booking location's local time. Format: YYYY-MM-DDThh:mm:ss
FormOfPaymentName The name of the form of payment for the booking.
FormOfPaymentType The type of the form of payment.
TicketMailingAddress The mailing address for the booked ticket, if available.
TicketPickupLocation The pickup location for the booked ticket, if available.
TicketPickupNumber The confirmation number to pick up the booked ticket, if available.
AirfareQuotes List of stored airfare quotes for this booking.
AirlineTickets List of Airline Tickets for this booking.
Charges List of Charges for this booking.
MiscChargeOrders List of Miscellaneous AirCharges for this booking.
Passengers The Passengers element contains a Passenger child element for each booked passenger. The description of each child element can be seen in a subsequent table.
PassPrograms List of Pass Programs for this booking.
PhoneNumbers List of Phone numbers associated with this booking.
RailPayments List of Rail payments associated with rail segments in this booking.
Segments List of Segments in this booking. This parent element contains one or more Air, Car, Hotel, Dining, Ride, Rail, Parking, or Event parent elements for the booking. Refer to Booking Object Elements for more information about the child elements contained in the booking elements.
Delivery The method this booking was delivered. 
WaitListSegments The segments that the traveler is waitlisted for this booking.
Warnings The warnings associated with the booking.
WebAddresses List of web addresses such as emails, pickup URLs, etc. associated with this bookings

Passenger Child Elements

Required Element Description
NameFirst The first name of the passenger.
NameLast The last name of the passenger.
Optional Element Description
NameMiddle The middle name of the passenger.
NamePrefix The name prefix of the passenger.
NameRemark Additional details about the passenger's name.
NameSuffix The name suffix of the passenger.
NameTitle The title of the passenger.
TextName The user's full name as entered in the booking tool if different from the name in the database.
FrequentTravelerProgram Passenger's loyalty programs

Response

This function returns the full trip details, as documented in the Response of the Get Itinerary Details function.

If the end user updates an existing reservation which results in a new confirmation number, the old booking must be explicitly cancelled in addition to posting the new booking to SAP Concur. If the previous booking is not cancelled, the user will see both bookings in their SAP Concur trip list.

Examples

Example 1: XML Example Request

POST /api/travel/booking/v1.0?tripId=12345678 HTTPS/1.1
Host: www.concursolutions.com
Authorization: OAuth {access token}
...
<Booking xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <Segments>
        <Car>
            <Vendor>AL</Vendor>
            <VendorName>Alamo</VendorName>
            <Status>HK</Status>
            <StartDateLocal>2013-12-21T12:00:00</StartDateLocal>
            <EndDateLocal>2013-12-23T12:00:00</EndDateLocal>
            <StartDateUtc>2013-12-21T20:00:00</StartDateUtc>
            <EndDateUtc>2013-12-23T20:00:00</EndDateUtc>
            <ConfirmationNumber>F16726AIUS</ConfirmationNumber>
            <DateCreatedUtc>2012-07-22T11:55:42</DateCreatedUtc>
            <DateModifiedUtc>2012-07-22T11:55:42</DateModifiedUtc>
            <StartCityCode>SEA</StartCityCode>
            <EndCityCode>SEA</EndCityCode>
            <StartLocation>SEA</StartLocation>
            <EndLocation>SEA</EndLocation>
            <Class>E</Class>
            <Body>C</Body>
            <Transmission>A</Transmission>
            <AirCondition>R</AirCondition>
            <NumPersons>1</NumPersons>
            <NumCars>1</NumCars>
            <DiscountCode>4321</DiscountCode>
            <DailyRate>35.0000</DailyRate>
            <TotalRate>105.0000</TotalRate>
            <RateType>D</RateType>
            <Currency>USD</Currency>
        </Car>
    </Segments>
    <RecordLocator>PANAMA50</RecordLocator>
    <BookingSource>Alamo</BookingSource>
    <DateCreatedUtc>2012-07-22T11:55:42</DateCreatedUtc>
    <DateModifiedUtc>2012-07-22T11:55:42</DateModifiedUtc>
    <DateBookedLocal>2013-11-10T13:01:00</DateBookedLocal>
    <Passengers>
        <Passenger>
            <PassengerKey>0</PassengerKey>
            <NameFirst>Chris</NameFirst>
            <NameLast>Miller</NameLast>
        </Passenger>
    </Passengers>
</Booking>

Example 2: XML Example of Successful Response

<Itinerary xmlns="https://www.concursolutions.com/api/travel/trip/2010/06">
    <id>https://www.concursolutions.com/api/travel/trip/v1.1/CNQR1234567890</id>
    <ItinLocator>CNQR1234567890</ItinLocator>
    <ClientLocator>KK-CNQ-1M1P6-5HJ</ClientLocator>
    <ItinSourceName>TravelSupplier</ItinSourceName>
    <TripName>Trip to Seattle</TripName>
    <Comments />
    <StartDateLocal>2013-12-21T07:25:00</StartDateLocal>
    <EndDateLocal>2013-12-23T23:59:00</EndDateLocal>
    <DateModifiedUtc>2012-07-24T19:15:52</DateModifiedUtc>
    <BookedVia>EveryGDS</BookedVia>
    <BookedByFirstName>Chris</BookedByFirstName>
    <BookedByLastName>Miller</BookedByLastName>
    <DateBookedLocal>2012-07-24T19:15:52</DateBookedLocal>
    <Booking>
        <Segments>
            <Car>
                <Vendor>AL</Vendor>
                <VendorName>Alamo</VendorName>
                <Status>HK</Status>
                <StartDateLocal>2013-12-21T12:00:00</StartDateLocal>
                <EndDateLocal>2013-12-23T12:00:00</EndDateLocal>
                <StartDateUtc>2013-12-21T20:00:00</StartDateUtc>
                <EndDateUtc>2013-12-23T20:00:00</EndDateUtc>
                <ConfirmationNumber>F16726AIUS</ConfirmationNumber>
                <DateCreatedUtc>2012-07-22T11:55:42</DateCreatedUtc>
                <DateModifiedUtc>2012-07-22T11:55:42</DateModifiedUtc>
                <StartCityCode>SEA</StartCityCode>
                <EndCityCode>SEA</EndCityCode>
                <StartLocation>SEA</StartLocation>
                <EndLocation>SEA</EndLocation>
                <Class>E</Class>
                <Body>C</Body>
                <Transmission>A</Transmission>
                <AirCondition>R</AirCondition>
                <NumPersons>1</NumPersons>
                <NumCars>1</NumCars>
                <DiscountCode>4321</DiscountCode>
                <DailyRate>35.0000</DailyRate>
                <TotalRate>105.0000</TotalRate>
                <RateType>D</RateType>
                <Currency>USD</Currency>
            </Car>
        </Segments>
        <RecordLocator>PANAMA50</RecordLocator>
        <BookingSource>Alamo</BookingSource>
        <DateCreatedUtc>2012-07-22T11:55:42</DateCreatedUtc>
        <DateModifiedUtc>2012-07-22T11:55:42</DateModifiedUtc>
        <DateBookedLocal>2013-11-10T13:01:00</DateBookedLocal>
        <ItinSourceName>TravelSupplier</ItinSourceName>
        <Passengers>
            <Passenger>
                <PassengerKey>0</PassengerKey>
                <NameFirst>Chris</NameFirst>
                <NameLast>Miller</NameLast>
            </Passenger>
        </Passengers>
    </Booking>
</Itinerary>

Cancel a Booking

Cancels an existing booking. By default, the OAuth consumer should be the owner of the booking. This endpoint can also be used to cancel bookings that the OAuth consumer does not own. This is most often done when a Travel Management Company needs to cancel bookings on behalf of a user. The TMC must be registered with SAP Concur and have a SAP Concur account that has one of the following user roles: Web Services Administrator for Professional, or Can Administer for Standard.

NOTE:

Example:

https://{baseUri}/api/travel/booking/v1.1/cancel?bookingSource={Supplier}&confirmationNumber={confnum}

Request

POST /api/travel/booking/v1.1/cancel?bookingSource={FastTravel}&confirmationNumber={098765431} HTTPS/1.1
Host: www.concursolutions.com
Authorization: OAuth {access token}

Request Parameters

Query Parameters - Required

The cancel keyword and the unique identifier for the supplier, configured by SAP Concur during the application review. The bookingSource must match the Supplier Name associated with the booking.

The confirmation number for the booking to cancel.

Example: https://www.concursolutions.com/api/travel/booking/v1.1/cancel?bookingSource={Supplier}&confirmationNumber={confnum}

Query Parameters - Optional

The SAP Concur login ID of the user who owns the booking. Only provided when the booking owner is not the OAuth consumer. Can only be used when the OAuth consumer has the required user role.

Example: https://www.concursolutions.com/api/travel/booking/v1.1/cancel?bookingSource={Supplier}&confirmationNumber={confnum}&userid_type=login_id&userid_value={loginID}

Content Type

application/xml

Authorization Header

The authorization header must have an OAuth token for valid SAP Concur user. The OAuth consumer must be registered as a Supplier or TMC with SAP Concur, and must have one of the following user roles in SAP Concur: Company Administrator or Web Services Administrator for Professional, or Can Administer for Standard.

Response

This function returns the full booking details, as specified in the Booking Object Elements section.

If the booking is not found, the function returns a HTTP 404 error and the following element:

Status: This element contains the value: NotFound.

Examples

Examples 1: XML Example Request

POST /api/travel/booking/v1.1/cancel?bookingSource={FastTravel}&confirmationNumber={098765431} HTTPS/1.1
Host: www.concursolutions.com
Authorization: OAuth {access token}

Examples 2: XML Example of Successful Response

<Car>
    <Vendor>ZE</Vendor>
    <Status>HK</Status>
    <StartDateLocal>2013-12-21T12:00:00</StartDateLocal>
    <EndDateLocal>2013-12-24T12:00:00</EndDateLocal>
    <TimeZoneId xsi:nil="true"/>
    <StartDateUtc>2013-12-21T20:00:00</StartDateUtc>
    <EndDateUtc>2013-12-24T20:00:00</EndDateUtc>
    <ConfirmationNumber>0987654321</ConfirmationNumber>
    <CancellationNumber>1029384756</CancellationNumber>
    <DateCreatedUtc>2012-07-22T11:55:42</DateCreatedUtc>
    <DateCancelledUtc>2012-07-25T14:21:35</DateCancelledUtc>
    <DateModifiedUtc>2012-07-22T11:55:42</DateModifiedUtc>
    <UpgradedDateTime xsi:nil="true"/>
    <IsUpgradeAllowed xsi:nil="true"/>
    <FrequentTravelerId/>
    <StartCityCode>SEA</StartCityCode>
    <EndCityCode>SEA</EndCityCode>
    <StartLocation>SEA</StartLocation>
    <EndLocation>SEA</EndLocation>
    <Class>E</Class>
    <Body>C</Body>
    <Transmission>M</Transmission>
    <AirCondition>R</AirCondition>
    <PhoneNumber/>
    <NumPersons xsi:nil="true"/>
    <NumCars>1</NumCars>
    <DiscountCode>346660</DiscountCode>
    <Charges>
        <Fixed>
            <Description>Dropoff Fee</Description>
            <Currency>USD</Currency>
            <Amount>0.0000</Amount>
            <StartDateLocal xsi:nil="true"/>
            <IsPaid xsi:nil="true"/>
            <SemanticsCode>DROPOFFFEE</SemanticsCode>
            <SemanticsVendorType>C</SemanticsVendorType>
        </Fixed>
        <RateWithAllowance>
            <Currency>USD</Currency>
            <Amount>44.0000</Amount>
            <StartDateLocal>2013-12-21T12:00:00</StartDateLocal>
            <IsPaid xsi:nil="true"/>
            <SemanticsCode>DAYS</SemanticsCode>
            <SemanticsVendorType>C</SemanticsVendorType>
            <PerUnit>DAY</PerUnit>
            <NumUnits>1.0000</NumUnits>
            <AllowanceUnit/>
            <AllowanceNumUnits>250.0000</AllowanceNumUnits>
            <AllowanceAmount>0.2400</AllowanceAmount>
            <AllowanceIsUnlimited>false</AllowanceIsUnlimited>
        </RateWithAllowance>
    </Charges>
    <Remarks/>
    <PerDiemLocation/>
</Car>

See Also

Trip resource

User

Users

The Users resource represents a set of SAP Concur users. It is always managed as a batch of users, even if the batch contains only one user.

Version

1.0

Process Flow

Process Flow for the User Resource

Retrieve a User's Information

This resource allows you to get profile information for a given user. If a request URL does not include a ?loginID parameter then the response will be for the logged in user (and you must pass authentication information with your request).

GET api/user/v1.0/user

Parameters

Name Type Format Description
loginID string - The URL-encoded SAP Concur login of the user. Optional.

Get User Response Schema

Name Type Format Description
loginID string - The user's login ID.
Active Boolean Y/N Whether the user is currently active.
FirstName string - The user's first name.
LastName string - The user's last name.
Mi string - The user's middle initial.
EmailAddress string - The user's email address.
EmpId string - The unique identifier for the user.
LedgerName string - The user's assigned account code ledger.
LocaleName string - The user's language locale code. One of the Supported Locales. Example: United States English is en_US.
OrgUnit1 through OrgUnit6 string - Varies depending on configuration.
Custom1 through Custom21 string - Varies depending on configuration. If the custom field is a list field, the data will be returned as: (list item short code) list item name. List Field Example: (1234) Project 1234
CtryCode string 2-character country code The user's two-digit country code.
CashAdvanceAccountCode string - The user's account code for cash advances.
CrnCode string ISO 4217 currency code The user's three character reimbursement currency. Example: United States Dollar is USD.
CtrySubCode string - The user's two-digit country code and two-digit state or province code. Example: Washington State, United States is US-WA.
ExpenseUser Boolean Y/N Whether the user has access to Expense.
ExpenseApprover Boolean Y/N Whether the user is an Expense approver.
TripUser Boolean Y/N Whether the user has access to Travel.
InvoiceUser Boolean Y/N Whether the user has access to Invoice.
InvoiceApprover Boolean Y/N Whether the user is an Invoice approver.
ExpenseApproverEmployeeID string - The employee ID of the user's Expense approver. If you are importing both a user and their approver, the approver should be listed before the user in the batch.
IsTestEmp Boolean Y/N Whether the user is a test user.

Retrieve All Users Based on Search Criteria

Note that this is a version 3.0 API and can be found here.

Retrieve the List of Required Fields for Creating a User

Retrieves a list of configured fields on the Global employee form in SAP Concur.

GET api/user/v1.0/FormFields

Required Fields Response Schema

Name Type Format Description
Id string - The unique field identifier.
Label string - The displayed field label.
ControlType string - The type of field.
DataType string - The type of data the field collects.
MaxLength string - The maximum length of data in the field.
Required string - Whether the field is required.
Cols string - The number of columns the field occupies.
Access string - The end-user access to the field.
Width string - The width of the field, in pixels.
Custom string - Whether the field is custom.
Sequence string - The sequence of the field on the form.

These elements are returned for Custom fields only:

Name Type Format Description
ParentFormTypeCode string - This element is only populated for multi-level list fields. The type of form that the parent field (the field one level higher in the list hierarchy) is connected to.
ParentFieldId string - The identifier for the field one level higher in the list hierarchy.
IsCopyDownSourceForOtherForms string - Whether the field is used as a copy down source by other forms.
ListName string - The name of the list associated with the field.
HierLevel string - The list level of the field. If it is the second level field in a two-level list, the value would be 2.

Update a User's Account Information

Updates one or more users. The batch can contain up to 500 users.

NOTE: The User API can be used to add new users, however the user accounts will not be fully configured and ready for use. Additional work to the user profiles must be completed, either with manual edits or updates via the user import, in order to complete the user profiles. There is a high degree of variability in customer configuration that is not all supported by this API. Manual edits or updates via a file import are most likely required to complete the User profiles started with this API. Only POST is supported. Please use the Employee Import feature if the User API does not meet your needs.

POST api/user/v1.0/users

This API requires as its arguments a batch element containing a UserProfile child element for each user to be added (in the future) or updated. The UserProfile child elements will vary depending on the form configuration, and may contain the following elements.

Update User Account Information Request Schema

Name Type Format Description
EmpId string - Required. The unique identifier for the user. The default value is the user's email address. Maximum 48 characters.
FeedRecordNumber string - Required. The record number in the current batch.
LoginId string - Required. The user's login ID. The default value is the user's email address. Maximum 128 characters.
LocaleName string - The user's language locale code. List of locale codes are available in the Employee Import Appendix. One of the Supported Locales. Example: United States English is en_US. The supported languages vary by company but always include en_US. Maximum: 5 characters.
Active Boolean Y/N Whether the user is currently active.
Password string - Required. The user's password. This element can be used to enter the password for a new user, but cannot be used to update the password for an existing user. Maximum 255 characters.
FirstName string - The user's first name. Maximum 32 characters.
LastName string - The user's last name. Maximum 32 characters.
Mi string - The user's middle initial. Maximum 1 character.
EmailAddress string - The user's email address. Maximum 255 characters.
LedgerKey string - Required for new users. The user's assigned account code ledger. Example: Default. Maximum 20 characters.
OrgUnit1 through OrgUnit6 string - The custom organizational unit fields on the Employee form. Varies depending on configuration. Use the Employee Form Field resource to get the list of configured fields. Maximum 48 characters for each field.
Custom1 through Custom21 string - The custom fields on the Employee form. Varies depending on configuration. Use the Employee Form Field resource to get the list of configured fields. Maximum 48 characters.
CtryCode string ISO 3166-1 alpha-2 country code Country code, example: United States is US. Maximum 2 characters.
CashAdvanceAccountCode string - The user's account code for cash advances. Maximum 20 characters.
CrnKey string ISO 4217 3-letter currency code Currency code for the user's reimbursement currency. Example: United States Dollar is USD. Maximum 3 characters.
CtrySubCode string - The user's two-character country code and two-character state or province code. Example: Washington State, United States is US-WA. Maximum 2 characters.
ExpenseUser Boolean Y/N Whether the user has access to Expense.
ExpenseApprover Boolean Y/N Whether the user is an Expense approver.
TripUser Boolean Y/N Whether the user has access to Travel.
InvoiceUser Boolean Y/N Whether the user has access to Invoice.
InvoiceApprover Boolean Y/N Whether the user is an Invoice approver.
ExpenseApproverEmployeeID string - The employee ID of the user's Expense approver. If you are importing both a user and their approver, the approver should be listed before the user in the batch. Maximum 48 characters.
NewLoginID string - Use this element to change the Login ID for an existing employee. Maximum 128 characters.
NewEmployeeID string - Use this element to change the Employee ID for an existing employee. Maximum 48 characters.

Update User Account Information Response Schema

Name Type Format Description
records-succeeded string - The number of records processed that were successfully added or updated.
records-failed string - The number of records processed that were not successfully added or updated.

When any users are successfully updated:

The request will return the UserDetails parent element with a UserInfo element for each successfully added or updated user. The UserInfo elements will contain the following child elements:

Name Type Format Description
EmployeeID string - The employee ID of the user.
FeedRecordNumber string - The item number of the record in the feed.
Status string - The status of the attempt to add or update the user. Should always contain the word SUCCESS.

When any users fail:

The request will return the errors parent element with an error parent element for each record failure. The error element will contain the following child elements:

Name Type Format Description
EmployeeID string - The employee ID of the user.
FeedRecordNumber string - The item number of the record in the feed.
Message string - The error message.

Example

<batch xmlns="http://www.concursolutions.com/api/user/2011/02">
    <UserProfile>
        <LoginID>loginID</LoginID>
        <EmployeeID>employeeID</EmployeeID>
        <Active>N</Active>
        <--! Any more required fields -->
    </UserProfile>
</batch>

Update a User's Password

POST api/user/v1.0/Users/password

Updates passwords for up to 500 users.

Update User's Password Request Schema

This function requires as its arguments a UserBatch element containing a User child element for each user. The User element must have the following elements:

Name Type Format Description
LoginID string - Required. The user's login ID. The default value is the user's email address.
Password string - The user's new password.

Update User's Password Response Schema

This request will return a BatchResult parent element with the following child elements:

Name Type Format Description
RecordsSucceeded string - The number of records processed that were successfully updated.
RecordsFailed string - The number of records processed that were not successfully updated.
UserPasswordStatusList string - This parent element will contains a UserPasswordStatus element for each user.

The UserPasswordStatus element contains the following child elements:

Name Type Format Description
LoginID string - The login ID of the user.
Status Boolean Success/Failed The status of the attempt to update the user's password.
Message string - Additional details about the success or failure of the request.

Example

<UserBatch xmlns="http://www.concursolutions.com/api/user/2011/02">
    <User>
        <LoginID>loginID</LoginID>
        <Password>password</Password>
    </User>
</UserBatch>

General

HTTP Status Codes

Successful Requests

The web services return a HTTP 2xx response code when the request was successful.

HTTP Success Codes:

Success Code Message Description
200 OK The request was received successfully.

Failed Requests

The web service should return a response within 60 seconds. If the request times out without a response, the application should wait for 5 minutes then retry the request.

The web service returns a 4xx or 5xx HTTP response code when there are any errors and will include the following elements:

Element Description
StatusCode The HTTP error code.
Content A parent element that contains an Error child element.

Error elements

Element Description
Message The error message.
Server-Time The time the error was generated, based on Concur's server's time zone.
Id The ID of the error within Concur.

Refer to the individual function documentation for function-specific error formats.

HTTP Error Codes

The full list of possible HTTP error codes can be found here. The table below provides additional details for commonly encountered error codes.

Error Code Message Description
400 Bad Request This response is returned if any of these conditions is true:

* The specified URI is invalid.
* The request is not formatted correctly.
* The request is missing a required field.
* The number of requests received exceed the request limit.
* The request encountered a database deadlock. In this case, the developer should resend the request a short time later.
* This error can be received if Chunked Transfer-Encoding is enabled by the developer's web server. Concur does not support Chunked Transfer-Encoding.

Attendee Web Service:

* The batch type parameter is not included on the URI of batch operations.
* The request contains 0 attendees.
* The request contains over 1000 attendees.

Imaging Web Service:

* The barcode or reportId is missing.

Purchase Order Web Service:

* The request contains 0 purchase orders.
* The request contains over 1000 purchase orders.

List Item Web Service:

* The request contains 0 list items.
* The request contains over 1000 list items.

Payment Batch File:

* The Batch ID specified in the URI is invalid.

Trip Approval:

* The request contains 0 itineraries.

User Web Service:

* The request contains 0 users.
* The request contains over 1000 users.
401 Unauthorized The Authorization header is not included in the request.
403 Forbidden This response is returned if any of these conditions is true:

* The Authorization header is included but it fails validation. This can happen if the OAuth consumer does not have access to the Concur product required by the web service.
* The partner application associated with the oauth_consumer_key has not been allowed access to the requested company.
* The Oauth token has expired or been revoked.
404 Not Found Extract Web Service: The Definition ID or Job ID specified in the URI is invalid.

Imaging Web Service: No image was found for the specified report Id or barcode.

Itinerary Web Service: The Trip ID or Booking ID specified in the URI is invalid.

Payment Batch Web Service: The Batch ID specified in the URI is invalid.
409 Conflict Extract Web Service: A job for the specified definition is already queued or running.
500 Internal Server Error/Not Closed Expense Report Web Service: This response is returned when the system is unable to calculate an exchange rate for a posted expense report entry.
Payment Batch Web Service: The specified batch could not be closed.
503 Service Unavailable This response is returned when the web service is down for maintenance. The partner application should sleep for 5 minutes then retry the request. If the request continues to fail after a few retries, the developer should contact concurconnecttech@concur.com.

Locale Codes

All Concur customers have the following locale set in their entities by default. This is the only locale that is available for all clients.

Default Locale

Locales Code
English (United States) en_US

Customers can request to have additional locales added to their entity if necessary. The following list includes all supported locales.

All Supported Locales Code
Bulgarian (Bulgaria) bg_BG
Chinese (China) zh_CN
Chinese (Hong Kong) zh_HK
Chinese (Taiwan) zh_TW
Croatian (Croatia) hr_HR
Czech (Czech Republic) cs_CZ
Danish (Denmark) da_DK
Dutch (Belgium) nl_BE
Dutch (Netherlands) nl_NL
English (Australia) en_AU
English (Canada) en_CA
English (India) en_IN
English (Ireland) en_IE
English (New Zealand) en_NZ
English (South Africa) en_ZA
English (United Kingdom) en_GB
English (United States) en_US
Finnish (Finland) fi_FI
French (Belgium) fr_BE
French (Canada) fr_CA
French (France) fr_FR
French (Luxembourg) fr_LU
French (Switzerland) fr_CH
German (Austria) de_AT
German (Germany) de_DE
German (Luxembourg) de_LU
German (Switzerland) de_CH
Hungarian (Hungary) hu_HU
Indonesian (Indonesia) id_ID
Italian (Italy) it_IT
Italian (Switzerland) it_CH
Japanese (Japan) ja_JP
Korean (North Korea) ko_KP
Korean (South Korea) ko_KR
Norwegian (Norway) no_NO
Polish (Poland) pl_PL
Portuguese (Brazil) pt_BR
Romanian (Romania) ro_RO
Russian (Russian Federation) ru_RU
Slovak (Slovakia) sk_SK
Spanish (Argentina) es_AR
Spanish (Bolivia) es_BO
Spanish (Chile) es_CL
Spanish (Colombia) es_CO
Spanish (Costa Rica) es_CR
Spanish (Dominican Republic) es_DO
Spanish (Ecuador) es_EC
Spanish (El Salvador) es_SV
Spanish (Guatemala) es_GT
Spanish (Honduras) es_HN
Spanish (Mexico) es_MX
Spanish (Nicaragua) es_NI
Spanish (Panama) es_PA
Spanish (Paraguay) es_PY
Spanish (Peru) es_PE
Spanish (Puerto Rico) es_PR
Spanish (Spain) es_ES
Spanish (Uruguay) es_UY
Spanish (Venezuela) es_VE
Swedish (Sweden) sv_SE
Thai (Thailand) th_TH
Turkish (Turkey) tr_TR

Spend Category Codes

The following table lists Spend Category codes that are used in several of the Concur APIs.

Code Name
ADVTG Advertising/Marketing
AIRFE Airline Fee
AIRFR Airfare
CARRT Car Rental
COCAR Company Car - Fixed Expense
COCRM Company Car Mileage
COMPU Computer
ENTER Entertainment
FEESD Fees/Dues
GASXX Gas
GOODW Goodwill
GRTRN Ground Transportation
LODGA Lodging - Track Hotel Spending
MEALS Meal
MEETG Meetings
OFFIC Office
OTHER Other
PRCAR Personal Car - Fixed Expense
PRCRM Personal Car Mileage (Expense Professional), Car Mileage (Expense Standard)
PRKNG Personal Car - Parking Expense
RAILX Rail
SHIPG Shipping
SUBSC Subscription/Publication
TELEC Telecom
TRADE Trade/Convention
TRAIN Training

Deprecated

SAP Concur Deprecated API List

The following application programming interfaces (APIs) have been deprecated according to the API Lifecycle & Deprecation Policy.

Attendees v1

This API has been deprecated.

Partners and customers using a deprecated API should contact SAP Concur and discuss moving to the latest versions.

Learn more in the API Lifecycle & Deprecation Policy.

The Shared attendees in the Concur company. Attendees added using this web service are added to the Shared Attendee List (owned by the System and available to all users). This resource can't be used to create attendees on a Private List.

URI

https://www.concursolutions.com/api/expense/attendees/v1.0/

This resource supports the following POST actions:

Post new attendee list

Adds one or more attendees. This request creates attendees that are part of the Shared List, which are available to all users. This function requires the attendee resource version 1.0.

Request

Parameters

Parameter Required/Optional Description
batch required The batch keyword.
type required The type of batch operation to complete. Should be create.

Example: https://www.concursolutions.com/api/expense/attendee/v1.0/batch?type=create

Headers

Payload

This function requires as its arguments an attendee-batch element containing an attendee child element for each attendee to be added. All batch operations allow up to 1000 attendees per batch. If a batch request with over 1000 attendees is sent, only the first 1000 attendees in the batch will be processed.

Attendee

Response

Headers

Payload

Example

Request

POST https://www.concursolutions.com/api/expense/attendee/v1.0/batch?type=create
Authorization: OAuth {access token}
Content-Type: application/xml
<attendee-batch xmlns="http://www.concursolutions.com/api/expense/attendee/2010/05">
  <attendee>
    <external-id>444543344</external-id>
    <type>BUSGUEST</type>
    <last-name>Miller</last-name>
    <first-name>Chris</first-name>
    <company>Len Dev</company>
    <currency-code>USD</currency-code>
    <custom1>345DERF</custom1>
  </attendee>
  <attendee>
    <external-id>444543345</external-id>
    <type>BUSGUEST</type>
    <last-name>Davis</last-name>
    <first-name>Pat</first-name>
    <company>Len Dev</company>
    <currency-code>USD</currency-code>
    <custom1>345DERK</custom1>
  </attendee>
</attendee-batch>

Response

HTTP/1.1 200 OK
Content-Type: application/xml
<attendee-batch-result xmlns="http://www.concursolutions.com/api/expense/attendee/2010/05" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
  <records-succeeded>1</records-succeeded>
  <records-failed>1</records-failed>
  <errors>
    <error>
      <code>1202</code>
      <external-id>444543345</external-id>
      <message>Missing attendee type</message>
    </error>
  </errors>
</attendee-batch-result>

Post attendee update list

Updates existing attendees. This request updates attendees that are part of the Shared List, which are available to all users. This function requires the attendee resource version 1.0.

Request

Parameters

Parameter Required/Optional Description
batch required Path: The batch keyword.
type required Query: The type of batch operation to complete. Should be update.

Example: https://www.concursolutions.com/api/expense/attendee/v1.0/batch?type=update

Headers

Payload

This function requires as its arguments an attendee-batch element containing an attendee child element for each attendee to be updated. All batch operations allow up to 1000 attendees per batch. If a batch request with over 1000 attendees is sent, only the first 1000 attendees in the batch will be processed.

Attendee

Response

Headers

Payload

Example

Request

POST https://www.concursolutions.com/api/expense/attendee/v1.0/batch?type=update
Authorization: OAuth {access token}
Content-Type: application/xml
<attendee-batch xmlns="http://www.concursolutions.com/api/expense/attendee/2010/05">
  <attendee>
    <external-id>444543344</external-id>
    <type>BUSGUEST</type>
    <last-name>Miller</last-name>
    <first-name>Chris</first-name>
    <company>Len Dev</company>
    <custom1>345DERL</custom1>
    <currency-code>USD</currency-code>
  </attendee>
</attendee-batch>

Response

HTTP/1.1 200 OK
Content-Type: application/xml
<attendee-batch-result xmlns="http://www.concursolutions.com/api/expense/attendee/2010/05" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
  <records-succeeded>1</records-succeeded>
  <records-failed>0</records-failed>
</attendee-batch-result>

Post an attendee inactivation list

Uses the update batch type to set existing attendees to Inactive. Attendees will be unavailable for new expense reports but will remain associated with existing expense reports. This function requires the attendee resource version 1.0.

Request

Parameters

Parameter Required/Optional Description
batch required Path: The batch keyword.
type required Query: The type of batch operation to complete. Should be update.

Example: https://www.concursolutions.com/api/expense/attendee/v1.0/batch?type=update

Headers

Payload

This function requires as its arguments an attendee-batch element containing an attendee - inactive child element for each attendee to be inactivated. All batch operations allow up to 1000 attendees per batch. If a batch request with over 1000 attendees is sent, only the first 1000 attendees in the batch will be processed.

Attendee - Inactive

Response

Headers

Payload

Example

Request

POST https://www.concursolutions.com/api/expense/attendee/v1.0/batch?type=update HTTP/1.1
Authorization: OAuth {access token}
Content-Type: application/xml
<attendee-batch xmlns="http://www.concursolutions.com/api/expense/attendee/2010/05">
  <attendee>
    <external-id>444543344</external-id>
    <inactive>true</inactive>
  </attendee>
</attendee-batch>

Response

HTTP/1.1 200 OK
Content-Type: application/xml
<attendee-batch-result xmlns="http://www.concursolutions.com/api/expense/attendee/2010/05" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
  <records-succeeded>1</records-succeeded>
  <records-failed>0</records-failed>
</attendee-batch-result>

Schema

NOTE: The element names are case-sensitive.

Attendee

Element Required/Optional Description
external-id required This is the unique identifier for the attendee from the external (to Concur) system. Maximum 48 characters.
type required The attendee type code. Refer to the Attendee Types v3 documentation. Maximum 8 characters.
last-name required The last name of the attendee. Maximum 132 characters.
first-name optional The first name of the attendee. Maximum 50 characters.
company optional The name of the attendee’s company. Maximum 150 characters.
title optional The attendee's title. Maximum 32 characters.
total-amount-ytd optional The year to date total amount for the attendee. This sets the starting value for year to date attendee spend amount calculations.
currency-code required, if total-amount-ytd is supplied Defines the currency to be used when totaling costs for the attendee. Must be a 3-letter ISO 4217 currency code for the currency. Maximum 3 characters.
customx required, if the field is required on the Attendee form There can be one element for each custom field that is configured on the attendee form. There are 20 possible custom fields for attendee forms. The numbering matches the Concur custom field numbering and is not necessarily sequential. If the attendee form has custom 1, custom 3 and custom 10 on it, the custom1, custom3, and custom10 elements should be included. Concur Expense is vastly configurable. Use the following process to get the list of custom fields configured for the Attendee form:
1. Use the Get Available Form Types function to get the code associated with the Attendee Detail View form.
2. Use the Get Form Data function to get the FormId for the specific attendee form that you wish to use.
3. Use the Get Form Field Details function to get the list of configured fields (including custom fields) for the attendee form.

Maximum 100 characters.

Attendee - Inactive

Element Required/Optional Description
external-id required This is the unique identifier for the attendee from the external (to Concur) system. Maximum 48 characters.
inactive required This is set to true to inactivate the attendee. Format: true/false

Attendee Batch Result

Element Description
records-succeeded The number of records processed successfully.
records-failed The number of records processed which failed.
errors An error parent element for each record failure.

Error

Element Description
code The code associated with the error.
external-id The external ID of the record that failed.
message The error message.

Attendees v2

This API has been deprecated.

Partners and customers using a deprecated API should contact SAP Concur and discuss moving to the latest versions.

Learn more in the API Lifecycle & Deprecation Policy.

Description

The attendees in the Concur company. This resource can be used to retrieve attendee information for any attendee in the Concur company, regardless of whether they are Private or Shared. In future releases, this resource will be enhanced to provide full attendee management functionality.

This API allows developers to manage attendees in Concur. The Attendee resource can be used to retrieve attendee information for private or shared attendees. In future releases, the Attendee resource will be updated with additional functionality for managing all attendees in Concur.

The Attendee resource manages attendees in batches, and can be used to add, update or inactivate attendees. This resource provides functionality similar to the Attendee List Import in Concur. Attendees added using this resource are added to the Shared Attendee List (owned by the system and available to all users).

Product Restrictions

Concur products are highly configurable, and not all clients will have access to all features.

Partner developers must determine which configurations are required for their solution prior to the review process.

Existing clients can work with Concur Advantage Technical Services to create custom applications that work with their configuration.

See also

URI

https://www.concursolutions.com/api/expense/v2.0/attendees

Resources

Get attendees

Retrieves the attendees matching the specified search criteria. Developers can specify one or more External IDs or the Attendee ID to search the Expense database.

Request

Parameters

Parameter Required/Optional Description
attendeeID optional Path: The unique identifier for the attendee in Concur. This information is returned in the AttendeeID element of the response of the Get Report Details function.
externalid optional Query: The unique identifier for the attendee outside of Concur. This information is returned in the ExternalID element of the response of the Get Report Details function. Up to 10 external IDs can be supplied in a comma separated list.

Examples:

https://www.concursolutions.com/api/expense/v2.0/attendees/{attendeeID}
https://www.concursolutions.com/apiexpense/v2.0/attendees?externalid={externalID}
https://www.concursolutions.com/apiexpense/v2.0/attendees?externalid={externalID1},{externalID2},{externalID3}

Headers

Get Attendee Details Response

Content Types

Content Body

This request will return an Attendees parent element containing an Attendee child element for each attendee.

Attendee elements

Element Description
AttendeeType The type of attendee. Maximum 40 characters.
FirstName The attendee's first name. Maximum 50 characters.
LastName The attendee's last name. Maximum 132 characters.
Company The attendee's company name. Maximum 150 characters.
Title The attendee's title. Maximum 32 characters.
ExternalID The unique identifier for the attendee, managed outside Concur. Maximum 48 characters.
Custom1 through Custom20 The details from the Custom fields. These may not have data, depending on configuration. For information about the child elements of this parent element, see the Custom child elements table below.
HasExceptionsPrevYear Whether the attendee has exceptions in the previous year, based on yearly total limits for attendees. Maximum 1 character. Format: Y/N
HasExceptionsYTD Whether the attendee has exceptions in the current year, based on yearly total limits for attendees. Maximum 1 character. Format: Y/N
IsDeleted Whether the attendee is marked as deleted. Maximum 1 character. Format: Y/N
OwnerEmpName The name of the employee that owns the attendee record.
TotalAmountPrevYear The total amount spent on the attendee in the previous calendar year.
TotalAmountYTD The total amount spent on the attendee in the current calendar year.
VersionNumber The attendee's version number.
AttendeeID Attendee unique identifier within Concur.
AttendeeTypeCode The unique identifier for the attendee type.
AttendeeOwnerID The unique identifier for the person or system that owns the attendee.
CurrencyCode The 3-letter ISO 4217 currency code for attendee related amounts.

Custom elements

Element Description
Type The custom field type. Will be one of the following: Amount, Boolean, ConnectedList, Date, Integer, List, Number, Text.
Value The value in the custom field. Maximum 100 characters.
Code Custom list fields will include the list item code in this element.

Examples

XML Example Request with Attendee ID

GET https://www.concursolutions.com/api/expense/v2.0/attendees/nFaAj0ncBsvkgnPMY5QWfBbbWyv$sQh2oW
Authorization: OAuth {token}

XML Example Request with External ID

GET https://www.concursolutions.com/api/expense/v2.0/attendees?externalid=234567
Authorization: OAuth {token}

XML Example of Successful Response

HTTP/1.1 200 OK
Content-Type: application/xml
<Attendees xmlns="http://www.concursolutions.com/api/expense/expensereport/2012/07" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
  <Attendee>
    <AttendeeType>BUSGUEST</AttendeeType>
    <FirstName>Chris</FirstName>
    <LastName>Miller</LastName>
    <Company />
    <Title />
    <ExternalID>234567</ExternalID>
    <Custom1 />
    <Custom2 />
    <Custom3 />
    <Custom4 />
    <Custom5 />
    <Custom6 />
    <Custom7 />
    <Custom8 />
    <Custom9 />
    <Custom10 />
    <Custom11 />
    <Custom12 />
    <Custom13 />
    <Custom14 />
    <Custom15 />
    <Custom16 />
    <Custom17 />
    <Custom18 />
    <Custom19 />
    <Custom20 />
    <HasExceptionsPrevYear>N</HasExceptionsPrevYear>
    <HasExceptionsYTD>N</HasExceptionsYTD>
    <IsDeleted>N</IsDeleted>
    <OwnerEmpName>Davis, Pat</OwnerEmpName>
    <TotalAmountPrevYear>0.00000000</TotalAmountPrevYear>
    <TotalAmountYTD>0.00000000</TotalAmountYTD>
    <VersionNumber>1</VersionNumber>
    <AttendeeID>nFaAj0ncBsvkgnPMY5QWfBbbWyv$sQh2oW</AttendeeID>
    <AttendeeTypeCode>BUSGUEST</AttendeeTypeCode>
    <AttendeeOwnerID>pd123456</AttendeeOwnerID>
    <CurrencyCode>USD</CurrencyCode>
  </Attendee>
</Attendees>

Responses and Errors

Refer to the HTTP Codes page for details of the common responses and errors.

Attendee List Errors

The web service will not return a 4xx HTTP response code for a batch operation even when every item in the batch failed to be created or updated. The client must inspect the response to look for warnings or errors with individual batch items.

When there are errors with batch items, the first ten errors are returned in the <errors> element in the request response, which includes their error code, the item that caused the error, and the error message. Any additional error messages are truncated. This prevents a large volume of error data in the event of a formatting mistake.

XML Response Error Codes

Error Code Message
1101 Could not find attendee-batch element.
1102 Error parsing attendee record X
1201 Missing external id for attendee record X
1202 Missing attendee type
1203 Missing currency code
1204 External id too long
1205 Attendee type too long
1206 Invalid inactive value.
1207 Attendee of type NOSHOWS ignored.
1208 Invalid currency code
1209 Missing required field X
1210 Invalid time stamp for field X
1211 Invalid money or money value for field X
1212 Invalid money or numeric value for field X
1213 Invalid integer for field X
1214 Invalid boolean value for field X
1215 Invalid char value for field X
1216 Invalid varchar value for field X
1217 Value too long for field X
1218 Invalid attendee type
1219 More than one value was specified for the X field in record X
1221 Invalid code for field X
1222 Missing code for field X
1301 Unexpected error creating attendee
1302 Unexpected error updating attendee
1303 Unexpected error getting attendee type list
1304 Unexpected error processing batch request.
1305 Cannot update the attendee data for a non existing attendee.

Attendee Types v1

This API has been deprecated.

Partners and customers using a deprecated API should contact SAP Concur and discuss moving to the latest versions.

Learn more in the API Lifecycle & Deprecation Policy.

Description

The Attendee Type resource represents the type of attendee as configured in Concur. Retrieves the list of attendee types for the company.

Version

1.0

URI

https://www.concursolutions.com/api/expense/attendee/v1.0/type

Get list of attendee types

Request

Parameters

None.

Headers

Response

Payload

This response will return an attendee-types parent element containing an attendee-type child element for each attendee type.

Element Description
type The attendee type code.
name The attendee type name.

Example

Request

GET https://www.concursolutions.com/api/expense/attendee/v1.0/type
Authorization: OAuth {access token}

Response

HTTP/1.1 200 OK
Content-Type: application/xml
<attendee-types xmlns="http://www.concursolutions.com/api/expense/attendee/2010/05" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
  <attendee-type>
    <type>BUSGUEST</type>
    <name>Business Guest</name>
  </attendee-type>
  <attendee-type>
    <type>EMPLOYEE</type>
    <name>Employee</name>
  </attendee-type>
</attendee-types>

Pre-2017 Authorization (Deprecated)

Authentication

This API has been deprecated.

Deprecation Date: 02/04/2017

If you are a new partner or an existing one creating a new app, please refer to the new authentication version documentation.

Please contact your Partner Enablement representative before starting any new development to ensure a smooth and successful certification process.

Pre-2017 Authorization - Access tokens

An access token is a long-lived token used to make API calls.

Verb and URIs

All authentication and authorization tasks use the GET verb and URI as noted here depending on type of application:

Type Verb + URI
Native GET https://{InstanceURL}/net2/oauth2/accesstoken.ashx
Web or Auto-Connect GET https://{InstanceURL}/net2/oauth2/GetAccessToken.ashx

Keys and Secrets

The Application Authorization section in the New Partner Application page includes Key and Secret fields that are used to generate a request token which is later exchanged for an access token.

Field URI Parameter Description
Key client_id Unique identifier for the application.
Secret client_secret Unique value for the application.

Getting an access token

Parameters

Name Type Format Description
code string {request_token} Required The request token.
client_id string {key} Required The application key.
client_secret string {secret} Required The application secret.

Input

None

Response

Name Type Format Description
Instance_URL string - Identifies the Concur datacenter where the user's data resides. For example, if the Instance_Url is https://www.ea1.concursolutions.com, then all API calls for this user should use this URL as a prefix in subsequent API calls
Token string - The access token value passed in the Authorization header when making API calls. It is a long-lived token which is currently set to expire after one year from creation. You should securely store the token and use it for all subsequent API requests until the token expires. Before it does, you should send a request to refresh the token prior to the expiration date.
Expiration_Date string - The Universal Coordinated Time (UTC) date and time when the access token expires.
Refresh_Token string - Token with a new expiration date of a year from the refresh date. You should securely store the refresh token for a user and use it for all subsequent API requests.

Refreshing an access token

NOTE: The token being refreshed must be used to make the refresh call.

Verb + URI
GET https://{InstanceURL}/net2/oauth2/getaccesstoken.ashx?refresh_token={your refresh token}&client_id={your_client_id}&client_secret={your_client_secret}

Parameters

Name Type Format Description
refresh_token string Refresh_Token Required The refresh token.
client_id string {key} Required The application key.
client_secret string {secret} Required The application secret.

Input

None

Response

Name Type Format Description
Instance_URL string - Identifies the Concur datacenter where the user's data resides. For example, if the Instance_Url is https://www.ea1.concursolutions.com, then all API calls for this user should use this URL as a prefix in subsequent API calls
Token string - The access token value passed in the Authorization header when making API calls. It is a long-lived token which is currently set to expire after one year from creation. You should securely store the token and use it for all subsequent API requests until the token expires. Before it does, you should send a request to refresh the token prior to the expiration date.
Expiration_Date string - The Universal Coordinated Time (UTC) date and time when the access token expires.

Revoking a single access token for a given user

POST https://{InstanceURL}/net2/oauth2/revoketoken.ashx

Note: To revoke tokens, the caller must have one of the following roles:

Headers

Header Format Description
Authorization https://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.8. OAuth {access_token} of user with proper role.

Parameters

Name Type Format Description
token string {access_token} Required The token to be revoked.

Response

None

Example

POST https://www.concursolutions.com/net2/oauth2/revoketoken.ashx?token=fdjhk2382kwkajsklwe8i3932kslswl Authorization: OAuth fdjhk2382kwkajsklwe8i3932kslswl

Revoking all access tokens for a user

POST https://www.concursolutions.com/net2/oauth2/revoketoken.ashx

Headers

Header Format Description
Authorization https://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.8. OAuth {access_token} of user with proper role.

Parameters

Name Type Format Description
consumerKey string {key} Required The key of the application.
user string {user_LoginID} Required The LoginID of the user.

Response

w None

Example

POST https://www.concursolutions.com/net2/oauth2/revoketoken.ashx?consumerKey=eZByXv2X41cJlC21pSVvRi&user=Maria Authorization: OAuth fdjhk2382kwkajsklwe8i3932kslswl

Choosing an authorization flow

Use this table to decide which OAuth 2.0 authorization flow to use for the application:

If you need to... Use this flow
Get an access token for prototyping, designing and testing an application. Native
Get an access token for a user with the Web Services Administrator role and don't require the user to assent (usually for back-office integration apps). Native
Inform the end-user how the app will access their data. Web or App Center
Have an end-user-facing app and wish to initiate the account linking from the app, outside of the Concur App Center. NOTE: These apps must also support App Center Flow so your app is available in the Mobile App Center. Most end-user apps will be used predominantly on a mobile device. Web
Distribute the app in the Mobile App Center App Center
Distribute the app in the App Center and are not a TripLink supplier. App Center
Distribute the app in the App Center and are a TripLink supplier. Auto-Connect

Native

The request must contain the following HTTP headers:

Headers

Header Format Description
Authorization https://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.8. The Base-64 encoded Concur credentials (LoginID:Password) of the user requesting access in the HTTP Basic Authentication format. If no password is used, the user name must still end with a colon.
X-ConsumerKey {key} Unique identifier for the application.

Example

GET {uri} Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ== X-ConsumerKey: hj7683jslks93lalkjss93

Response

Access token response

Web

There are two types of access levels that can be enabled with web flow:

Type Description
Company Level A company can enable an application to use their data in Concur.
User Level A user can enable apps to use their individual data.

This is determined by the type of Concur user account used in the process.

The web flow is as follows:

  1. Application redirection to the Concur website for authentication and authorization.
  2. Parse of a inbound HTTP request from the Concur system to an application specified endpoint.
  3. Getting an access token

Application Redirection to the Concur website for authentication and authorization.

https://www.concursolutions.com/net2/oauth2/Login.aspx?{parameters}

Parameters

Name Type Format Description
client_id string {key} Required The application key.
scope string {scope} The comma separated list of APIs for which authorization will be granted.
redirect_uri string - The URI of the partner application where Concur will redirect the user after authentication and access approval.
state string - Optional partner application-defined state variable. This variable is specified by the partner application and will be returned intact by the Concur's OAuth provider when the user is redirected to the redirect URL. Values are generally passed in this parameter when the state of the value cannot be maintained by the partner application, for instance when making calls between multiple, disparate web pages. Example: The state variable can contain the ID of the user in the partner application, so that the token returned in the callback can be associated to the specified user and subsequently saved in the database of the partner application.
Scope Description
ATTEND Attendee List Web Service
CONFIG Expense Configuration Web Service
ERECPT E-Receipts Web Service
EXPRPT Expense Report Web Service, Quick Expense Web Service
EXTRCT Extract Web Service
IMAGE Imaging Web Service
INSGHT Insights Web Service
INVPO Invoice Purchase Order Web Service
ITINER Itinerary Web Service
LIST List Item Web Service
MTNG Meeting Web Service
PAYBAT Payment Batch Web Service
TRVPRF Travel Profile Web Service
TRVREQ Travel Request Web Service
TWS Trip Approval Web Service
USER User Web Service

Parse of a inbound HTTP request from the Concur system to an application specified endpoint.

http://{redirect_uri}?{parameters}

Parameters
Name Type Format Description
error string - The name of the error.
error_description string - Description of the error.
code string {request_token} The request token.

AppCenter

The AppCenter flow is as follows:

  1. Listening for an HTTP GET request from the Concur system.
    • The listener must be hosted at the URI specified in the App Center listing.
    • The request will be in this form: GET {listener_URI}?code={request_token}
  2. Parsing the request token value from the code query parameter.
  3. Getting an access token

Auto-Connect

The Auto-Connect flow is an authorization to support Connection Requests API calls from TripLink applications. During the Auto-Connect flow, the request token associated with a TripLink application is exchanged for an access token for the user who granted the TripLink application access to the user's Concur data.

  1. Periodically getting a list of connection requests.

    GET /common/connectionrequests

  2. For each user in the connection requests response: Getting an access token

  3. For each connection request, call any other Concur APIs you need to match the Concur user with the user in your system. When the user is successfully matched, or when matching fails, update the connection request.

    PUT /common/connectionrequests/{id}

  4. If you encounter an error that makes it impossible to complete the connection process, revoke the access token so the user knows that the connection attempt failed and they can try again at a later time.

Expense Entry Itemization v1.1

This API has been deprecated.

Deprecation Date: 05/19/2016

Unsupported Date: 11/19/2016

Partners and customers using a deprecated API should contact SAP Concur and discuss moving to the latest versions.

Learn more in the API Lifecycle & Deprecation Policy.

Expense Entry Itemizations are children of an expense entry that subdivide the expense. A common use case for itemizations is on a hotel bill, which can have separate itemizations for room rate, room tax, and services such as laundry or minibar.

URI

https://www.concursolutions.com/api/expense/expensereport/v1.1/report/{reportId}/entry/{entryId}/itemization/{itemizationId}

POST Expense Entry Itemization

Creates or updates an itemization record for the specified expense entry.

NOTE: Posting expense report information is a multi-stage process. Refer to the Processes section of the Expense Report Web Service page for the steps required to post new expense reports and entries.

Request

Request parameters

Parameters

Parameter Required/Optional Description
{_reportId_} Required The unique identifier for the expense report.
{_entryId_}/Itemization Required The unique identifier for the expense entry and the Itemization keyword.
{_itemizationID_} Optional The unique identifier for the itemization.

Examples:

https://www.concursolutions.com/api/expense/expensereport/v1.1/report/{reportId}/entry/{entryId}/itemization
https://www.concursolutions.com/api/expense/expensereport/v1.1/report/{reportId}/entry/{entryId}/itemization/{itemizationId}

URI Sources

Headers

The OAuth Consumer must have one of the following roles to post itemizations for expenses in reports that they do not own: Web Services Admin for Professional, or Can Administer for Standard.

Content-Type header

application/xml

Payload

This request contains an ExpenseItemizations parent element with an Itemization parent element for each included itemization. The Itemization parent element has the following child elements.

Itemization elements

Element Required (must contain value)? Description
ExpKey Y The expense type key for the expense. Expense Type Keys are returned in the ExpKey element by the Get Expense Group Configuration endpoint. The expense type key cannot be modified when updating expense entries.
Description Depends on configuration The description for the expense.
TransactionAmount Y The total amount of the itemization in the original currency, with up to three decimal places. Example: 123.654
PostedAmount Depends on configuration The amount of the itemization in the user's reimbursement currency, with up to three decimal places. Example: 123.654. May vary from transaction amount if some of the expense is marked personal or if it has been converted to another currency. See Notes for more information.
Custom1 through Custom20 Depends on configuration The Expense Entry Form custom fields. Itemizations are child entries to the expense entry, and they share the custom fields. May be required depending on configuration. Refer to the Processes, Post Expense Report Data section of Expense Report for the steps necessary to gather required field information.
NOTE: If any of the custom fields are configured to contain list values, please refer to the Posting Custom List Items page for information on how to correctly submit list item values.
IsPersonal N Whether the expense entry is a personal expense. Personal expenses are not reimbursed in Concur Expense. Personal expenses cannot be itemized. Format: N
Comment Depends on configuration The itemization comment.

NOTES:

Response

Payload

This request will return an ItemizationStatusList parent element with an ItemizationStatus child element for each posted itemization. The ItemizationStatus element will contain the following child elements.

ItemizationStatus elements

Element Description
Index The entry's sequence in the request.
Status The status of the request. Possible values are:
200: The itemization was successfully saved.
400: The Request includes an error such as a syntax error or missing required element.
404: The Itemization URI is in the correct syntax, but the system can't find the itemization. It may have been deleted from the system.
500: The request has the correct syntax and refers to an existing itemization, but the system was unable to save due to a system conflict.
Itemization-Url The URI to get the itemization details.

Examples

XML example request

POST https://www.concursolutions.com/api/expense/expensereport/v1.1/report/nxxKgLlnROz$sQ6SKJFjLNs4OWBErcJ8yX/entry/nE0avYnILNNi9qkVyS3lYPuv4Mop4QmVs/Itemization HTTP/1.1
Authorization: OAuth {access token}
Content-Type: application/xml
<ExpenseItemizations xmlns="http://www.concursolutions.com/api/expense/expensereport/2011/03">
  <Itemization>
    <ExpKey>DINNR</ExpKey>
    <Description>Dinner</Description>
    <TransactionAmount>56.00</TransactionAmount>
    <PostedAmount>56.00</PostedAmount>
    <Comment>Dinner</Comment>
    <Custom1>Dinner</Custom1>
    <Custom2>Room Service</Custom2>
    <Custom5>Too late for restaurant</Custom5>
    <IsPersonal>N</IsPersonal>
  </Itemization>
  <Itemization>
    <ExpKey>LUNCH</ExpKey>
    <Description>Lunch</Description>
    <TransactionAmount>24.64</TransactionAmount>
    <PostedAmount>24.64</PostedAmount>
    <Comment>Lunch</Comment>
    <IsPersonal>N</IsPersonal>
  </Itemization>
  <Itemization>
    <ExpKey>BRKFT</ExpKey>
    <Description>BreakFast</Description>
    <TransactionAmount>15.34</TransactionAmount>
    <PostedAmount>15.34</PostedAmount>
    <Comment>Breakfast</Comment>
    <IsPersonal>N</IsPersonal>
  </Itemization>
</ExpenseItemizations>

XML example response

HTTP/1.1 200 OK
Content-Type: application/xml
<ItemizationStatusList xmlns="http://www.concursolutions.com/api/expense/expensereport/2011/03" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
  <ItemizationStatus>
    <Index>1</Index>
    <Status>SUCCESS</Status>
    <ItemizedEntry-Details-Url>https://www.concursolutions.com/api/expense/expensereport/v1.1/report/nxxKgLlnROz3zHJBCRk$puJLmXp25RsAwp/entry/nE0avYnILNNi9qkVyS3lYPuv4Mop4QmVs/itemization/nE0avYnILN69JgpJGuSCy5qqirEfFcds4</ItemizedEntry-Details-Url>
  </ItemizationStatus>
  <ItemizationStatus>
    <Index>2</Index>
    <Status>SUCCESS</Status>
    <ItemizedEntry-Details-Url>https://www.concursolutions.com/api/expense/expensereport/v1.1/report/nxxKgLlnROz3zHJBCRk$puJLmXp25RsAwp/entry/nE0avYnILNNi9qkVyS3lYPuv4Mop4QmVs/itemization/nE0avYnILN65lGE4Zka1YOp608re6ASJb</ItemizedEntry-Details-Url>
  </ItemizationStatus>
  <ItemizationStatus>
    <Index>3</Index>
    <Status>SUCCESS</Status>
    <ItemizedEntry-Details-Url>https://www.concursolutions.com/api/expense/expensereport/v1.1/report/nxxKgLlnROz3zHJBCRk$puJLmXp25RsAwp/entry/nE0avYnILNNi9qkVyS3lYPuv4Mop4QmVs/itemization/nE0avYnILN6nw6Hi0jhAuYXAXiXNej7zb</ItemizedEntry-Details-Url>
  </ItemizationStatus>
</ItemizationStatusList>

Expense Entry v1.1

This API has been deprecated.

Partners and customers using a deprecated API should contact SAP Concur and discuss moving to the latest versions.

Learn more in the API Lifecycle & Deprecation Policy.

An expense entry in an expense report.

NOTE: You can find version 3.0 here

URI

https://www.concursolutions.com/api/expense/expensereport/v1.1/report/{reportId}/entry/{entryId}

Get Expense Entry Details Request

Retrieves the details for the specified expense entry

Supported Accept Types

application/xml

Parameters

Query Parameter Description
{_reportId_} Reqired The unique identifier for the expense report.
{_entryId_} The unique identifier for the expense entry.

Request Headers

XML Example Request

GET https://www.concursolutions.com/api/expense/expensereport/v1.1/report/nxxKgLlnROz3zHJBCRksaas23dsfs/entry/n7We3qWw99u1KoWTMaLhSC$pXBYzQ1UDhn HTTP/1.1
Authorization: OAuth {access token}

Response

This request will return an ExpenseEntry parent element with the following child elements:

Element Description
ApprovedAmount The approved amount of the entry in the user's reimbursement currency. The Get Report Details function returns the report currency, which is the user's reimbursement currency, in the CrnCode element.
Attendee-Url The URL to the attendees list for the entry.
Allocation-Url The URL to the allocations list for the entry.
BusinessPurpose The business purpose field from the report header.
EreceiptId The ID for the attached e-receipt, if available.
ExchangeRate The exchange rate that applies to the entry.
ExpenseKey The expense type key for the entry. Use the Get Expense Group Configuration endpoint to get the full list of expense types.
ExpenseName The expense type for the entry.
SpendCategory The spend category specified for this expense type. Varies by client, used in reporting.
HasAllocation Defines the amount of allocations for the expense. Possible values are: P, for partial allocation, F, for full allocation, or N, for no allocation.
HasAttendees Whether the expense has attendees.
HasComments Whether the expense has comments.
HasExceptions Whether the expense has exceptions.
HasVat Whether the expense has VAT data.
ImageRequired Whether a receipt image is required for the entry.
IsCreditCardCharge Whether the expense came from a credit card feed.
IsItemized Whether the expense has itemizations.
Itemizations-Url The URL to the itemization list.
IsPersonal Whether the expense is personal.
IsPersonalCardCharge Whether the expense came from a personal card feed.
LastModified The UTC date when the entry was last modified.
LocationName The location for the expense entry, usually the city name.
OrgUnit1 through OrgUnit6 The details from the Org Unit custom fields. These may not have data, depending on configuration.
PaymentTypeKey The key for the payment type for the entry. Use the Get Expense Group Configuration function to map the payment type key to the payment type name.
PostedAmount The amount of the expense entry in the user's reimbursement currency. The Get Report Details function returns the report currency, which is the user's reimbursement currency, in the CrnCode element.
ReceiptImageId The ID for the receipt image attached to the entry.
ReceiptRequired Whether the original receipt is required for the entry.
ReportEntryID The ID of the report entry.
ReportID The unique key of the report the entry is in.
TransactionAmount The amount of the expense entry in the original transaction currency.
TransactionCurrencyName The currency name of the expense entry transaction amount.
TransactionDate The date of the expense entry.
VendorDescription The vendor name of the expense entry, which can be entered manually by the user or imported from the card transaction Merchant Name field.
X_UserID The user ID associated with the entry.
Custom1 through Custom40 The details from the Custom fields. These may not have data, depending on configuration. If the custom field is a list field, the data will be returned as: (list item short code) list item name. List Field Example: (1234) Project 1234

XML Example of Successful Response

HTTP/1.1 200 OK
Content-Type: application/xml
<ExpenseEntry xmlns="http://www.concursolutions.com/api/expense/expensereport/2011/03" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
    <ApprovedAmount>40.00000000</ApprovedAmount>
    <Attendee-Url>https://www.concursolutions.com/api/expense/expensereport/v1.1/report/nYO0ck05r5fATbnjrMBf0d$sCIBqX8WQYw/entry/nbmTPob9qSUJWKttTEr6MLaXaPKYYPv7U/Attendees
    </Attendee-Url>
    <Allocation-Url>https://www.concursolutions.com/api/expense/expensereport/v1.1/report/nYO0ck05r5fATbnjrMBf0d$sCIBqX8WQYw/entry/nbmTPob9qSUJWKttTEr6MLaXaPKYYPv7U/Allocations</Allocation-Url>
    <BusinessPurpose />
    <EreceiptId />
    <ExchangeRate>1.00000000000000</ExchangeRate>
    <ExpenseKey>BUSML</ExpenseKey>
    <ExpenseName>OTHER</ExpenseName>
    <SpendCategory>Miscellaneous</SpendCategory>
    <HasAllocation>N</HasAllocation>
    <HasAttendees>Y</HasAttendees>
    <HasComments>N</HasComments>
    <HasExceptions>N</HasExceptions>
    <HasVat>N</HasVat>
    <ImageRequired>N</ImageRequired>
    <IsCreditCardCharge>N</IsCreditCardCharge>
    <IsItemized>N</IsItemized>
    <Itemizations-Url>https://www.concursolutions.com/api/expense/expensereport/v1.1/report/nYO0ck05r5fATbnjrMBf0d$sCIBqX8WQYw/entry/nbmTPob9qSUJWKttTEr6MLaXaPKYYPv7U/Itemization</Itemizations-Url>
    <IsPersonal>N</IsPersonal>
    <IsPersonalCardCharge>N</IsPersonalCardCharge>
    <LastModified>2011-06-18T16:03:31</LastModified>
    <LocationName />
    <PaymentTypeKey>CASH</PaymentTypeKey>
    <PostedAmount>40.00000000</PostedAmount>
    <ReceiptImageId />
    <ReceiptRequired>N</ReceiptRequired>
    <ReportEntryID>nbmTPob9qSUJWKttTEr6MLaXaPKYYPv7U</ReportEntryID>
    <ReportID>nYO0ck05r5fATbnjrMBf0d$sCIBqX8WQYw</ReportID>
    <TransactionAmount>40.00000000</TransactionAmount>
    <TransactionCurrencyName>US, Dollar</TransactionCurrencyName>
    <TransactionDate>2011-06-15T00:00:00</TransactionDate>
    <VendorDescription />
    <X_UserID>cmiller@example.com</X_UserID>
    <OrgUnit1 />
    <OrgUnit2 />
    <OrgUnit3 />
    <OrgUnit4 />
    <OrgUnit5 />
    <OrgUnit6 />
    <Custom1>Value</Custom1>
    <Custom2 />
    <Custom3 />
    <Custom4 />
    <Custom5 />
    <Custom6 />
    <Custom7 />
    <Custom8 />
    <Custom9 />
    <Custom10 />
    <Custom11 />
    <Custom12 />
    <Custom13 />
    <Custom14 />
    <Custom15 />
    <Custom16 />
    <Custom17 />
    <Custom18 />
    <Custom19 />
    <Custom20 />
    <Custom21 />
    <Custom22 />
    <Custom23 />
    <Custom24 />
    <Custom25 />
    <Custom26 />
    <Custom27 />
    <Custom28 />
    <Custom29 />
    <Custom30 />
    <Custom31 />
    <Custom32 />
    <Custom33 />
    <Custom34 />
    <Custom35 />
    <Custom36 />
    <Custom37 />
    <Custom38 />
    <Custom39 />
    <Custom40 />
</ExpenseEntry>

Post Expense Entry Request

Posts an expense report entry for the specified report. Use the Post Expense Report Header function to create the report, then use this endpoint to create the expense line items. You can update existing expense entries using this endpoint.

NOTE: Posting new expense reports is a multi-stage process. Refer to the Processes section of the Expense Report Web Service page for the steps required to post new expense reports and entries.

NOTE: Concur recommends that you post one expense entry per request. Future versions of this endpoint will require this behavior.

Supported Content Types

application/xml

Parameters

Query Parameters - Required Query Parameters - Optional
{_reportId_}/entry Required The unique identifier for the expense report and the entry keyword. Example: https://www.concursolutions.com/api/expense/expensereport/v1.1/report/_{reportId}_/entry.

URI Source: The reportId value is returned in the ReportID element by the Get List of Reports function, and as part of the Report-Details-Url element of the Post Expense Report Header function.
{_entryId_} The unique identifier for the expense entry. Example: https://www.concursolutions.com/api/expense/expensereport/v1.1/report/_{reportId}_/entry/{_entryId_}.

URI Source: The entryId value is returned in the RpeKey element of the Expense Report Full Details v1.1 function, and as part of the Report-Entry-Details-Url value returned by this function.

Request Headers

Payload

This request should contain a ReportEntries parent element with an Expense parent element for each included entry. The Expense element contains the following child elements:

Element Required (must contain value)? Description
CrnCode Y The 3-letter ISO 4217 currency code for the expense transaction amount. Example: USD.
ExpKey Y The expense type key for the expense. Required for new or updated entries. Expense Type Keys are returned in the ExpKey element by the Get Expense Group Configuration function. The expense type key cannot be modified when updating expense entries.
Description Depends on configuration The description for the expense, also known as business purpose. This information is returned in the BusinessPurpose element by the Get Report Details function. Refer to the Processes > Post Expense Report Data section of Expense Report for the steps necessary to gather required field information.
TransactionDate Y, for new entries The date the expense was incurred. Format: YYYY-MM-DD
TransactionAmount Y The total amount of the expense in the original currency, with up to three decimal places. Example: 123.654
LocationID Depends on configuration The Location code. May be required, if the City field is required. Use the Get Location function to retreive the valid values for this field. Refer to the Processes > Post Expense Report Data section of Expense Report for the steps necessary to gather required field information.
OrgUnit1 through OrgUnit6 Depends on configuration The Expense Entry Form org unit fields. May be required depending on configuration. Refer to the Processes > Post Expense Report Data section of Expense Report for the steps necessary to gather required field information.
Custom1 through Custom40 Depends on configuration The Expense Entry Form custom fields. May be required depending on configuration. Refer to the Processes > Post Expense Report Data section of Expense Report for the steps necessary to gather required field information. NOTE: If any of the custom fields are configured to contain list values, please refer to the Posting Custom List Items page for information on how to correctly submit list item values.
ExchangeRate N The exchange rate between the transaction and posted amounts. This element is typically not provided. If this element is empty for transactions in a currency different than the user's reimbursement currency, Expense will use the company's configured exchange rates to determine the posted amount for the transaction. If the system is not able to determine the exchange rate, the request will return an HTTP 500 error.
Comment Depends on configuration The expense entry comment. Max length: 2000. Refer to the Processes > Post Expense Report Data section of Expense Report for the steps necessary to gather required field information.
VendorDescription N, but recommended for sandbox This element contains the descriptive text for the vendor for the entry. This field is not required to successfully post an entry, however the field is a required field for expense entries in the developer sandbox. If this field is not provided for the sandbox, you will see an exception in the user interface stating that a required field is missing.
IsPersonal N Whether the expense entry is a personal expense. Personal expenses are not reimbursed in Concur Expense. Format: Y/N
PaymentTypeID N The unique identifier for the payment type for the expense entry. Use the PaymentTypeID value from the Get Expense Group Configuration endpoint. If you do not provide this value, the payment type defaults to Cash. The supported Payment Type Codes are: Cash and Company Paid.  The Pending Card Transaction system payment type is also supported, if the client has configured their company to use it.

NOTES

XML Example Request

POST https://www.concursolutions.com/api/expense/expensereport/v1.1/report/nxxKgLlnROz$sQ6SKJFjLNs4OWBErcJ8yX/entry/ HTTP/1.1
Authorization: OAuth {access token}
Content-Type: application/xml
<ReportEntries xmlns="http://www.concursolutions.com/api/expense/expensereport/2011/03">
  <Expense>
    <CrnCode>USD</CrnCode>
    <ExpKey>BUSPR</ExpKey>
    <Description>Business Promotions</Description>
    <TransactionDate>2011-01-12</TransactionDate>
    <TransactionAmount>29.23</TransactionAmount>
    <Comment>Brochure sample</Comment>
    <VendorDescription>Kinkos</VendorDescription>
    <IsPersonal>N</IsPersonal>
  </Expense>
  <Expense>
    <CrnCode>USD</CrnCode>
    <ExpKey>BRKFT</ExpKey>
    <Description>Description</Description>
    <TransactionDate>2011-01-12</TransactionDate>
    <TransactionAmount>15.54</TransactionAmount>
    <Comment>Breakfast meeting</Comment>
    <VendorDescription>Starbucks</VendorDescription>
    <IsPersonal>N</IsPersonal>
  </Expense>
</ReportEntries>

Response

Supported Content Types

application/xml

Payload

This request will return a ReportEntryStatusList parent element with the ReportEntryStatus child element for each posted entry. The ReportEntryStatus element will contain the following child elements:

Element Description
Index The entry's sequence in the request.
Status The status of the request.
Message When the status is FAILED, the details of the failure appear in this element.
Report-Entry-Details-Url The URI to get the expense entry details.

XML Example of Successful Response

HTTP/1.1 200 OK
Content-Type: application/xml
<ReportEntryStatusList xmlns="http://www.concursolutions.com/api/expense/expensereport/2011/03" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
  <ReportEntryStatus>
    <Index>1</Index>
    <Status>SUCCESS</Status>
    <Report-Entry-Details-Url>https://www.concursolutions.com/api/expense/expensereport/v1.1/report/nxxKgLlnROz$sQ6SKJFjLNs4OWBErcJ8yX/entry/nE0avYnILN9mHdTErNSd2pH45udFoNQ$po</Report-Entry-Details-Url>
  </ReportEntryStatus>
  <ReportEntryStatus>
    <Index>2</Index>
    <Status>SUCCESS</Status>
    <Report-Entry-Details-Url>https://www.concursolutions.com/api/expense/expensereport/v1.1/report/nxxKgLlnROz$sQ6SKJFjLNs4OWBErcJ8yX/entry/awEDvYnILN9g$s6lCFX0jFBWmHAiTYYf9C</Report-Entry-Details-Url>
  </ReportEntryStatus>
</ReportEntryStatusList>

Expense Entry Attendee v2

This API has been deprecated.

Partners and customers using a deprecated API should contact SAP Concur and discuss moving to the latest versions.

Learn more in the API Lifecycle & Deprecation Policy.

NOTE: Find the newer version 3.0 here.

The Expense Entry Attendees manages the relationship between the attendees and the expense report and entry, for the specified expense entry. This resource does not include the full attendee information, which can be accessed using the Get Attendees function.

URI

https://www.concursolutions.com/api/expense/expensereport/v2.0/report/{reportID}/entry/{entryID}/attendees

PUT Expense Entry Attendees

This allows the developer to specify which existing attendees are associated to the specified entry. It also gives the developer the option to provide the values for the Entry-Attendee association. The list of attendees in the request will replace any existing associated attendees, so the developer must include all attendees in the request. This function cannot be used to create new attendees.

Request

Parameters

Parameter Required/Optional Description
{_reportId_} Required The unique identifier for the expense report. This value is returned in the ReportID element by the Get Report Details function.
{_entryId_}/attendees Required The unique identifier for the expense entry and the Attendees keyword. This value is returned in the ReportEntryID element by the Get Report Details function.

Headers

Payload

XML: The request will contain an EntryAttendees parent element with an Attendee child element for each attendee associated to the entry.

JSON: The request string will contain an object for each attendee associated to the entry.

The request must include all attendees associated to the entry. To detach a previously attached attendee, use a Put request excluding the attendee. The function always associates only the attendees specified in the Put. To not modify the element or name/value pair value, provide a nill (XML) or null (JSON) value, or use the same value as you received in the Get Expense Entry Attendees response.

Attendee elements

The Attendee element (XML) or attendee object (JSON) must contain all of the following elements(XML) or name/value pairs(JSON):

Element Name Data Type Description
Amount decimal The portion of the Entry Transaction Amount assigned to this attendee.
AssociatedAttendeeCount int The count of attendees associated to this attendee. A count greater than 1 means there are unnamed attendees associated with this attendee.
AttendeeID string The unique identifier for the attendee.
EntryAttendeeCustom1 string The value for Entry-Attendee custom fields 1-5. Varies based on configuration.
EntryAttendeeCustom2 string The value for Entry-Attendee custom fields 1-5. Varies based on configuration.
EntryAttendeeCustom3 string The value for Entry-Attendee custom fields 1-5. Varies based on configuration.
EntryAttendeeCustom4 string The value for Entry-Attendee custom fields 1-5. Varies based on configuration.
EntryAttendeeCustom5 string The value for Entry-Attendee custom fields 1-5. Varies based on configuration.

Response

Headers

Examples

XML example request

PUT https://www.concursolutions.com/api/expense/expensereport/v2.0/report/9d8ea1kole$sis293mn38dh/entry/8sle90wikl3h$halwnk$lakdjw83/attendees HTTP/1.1
Authorization: OAuth {access token}
Content-Type: application/xml
<EntryAttendees xmlns="http://www.concursolutions.com/api/expense/expensereport/2012/07" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
  <Attendee>
    <Amount>2422.00000000</Amount>
    <AssociatedAttendeeCount>1</AssociatedAttendeeCount>
    <AttendeeID>nFaAj0ncBso0sBd8ejqrxLHz1FfmhJ69b</AttendeeID>
    <EntryAttendeeCustom1>fg6rt</EntryAttendeeCustom1>
    <EntryAttendeeCustom2>9808</EntryAttendeeCustom2>
    <EntryAttendeeCustom3>64564drd</EntryAttendeeCustom3>
    <EntryAttendeeCustom4>352dsxcvs</EntryAttendeeCustom4>
    <EntryAttendeeCustom5 i:nil="true"/>
  </Attendee>
</EntryAttendees>

JSON example request

PUT https://www.concursolutions.com/api/expense/expensereport/v2.0/report/9d8ea1kole$sis293mn38dh/entry/8sle90wikl3h$halwnk$lakdjw83/attendees HTTP/1.1
Authorization: OAuth {access token}
Content-Type: application/json
[
  {
    "AttendeeID": "nFaAj0ncBs$puDs5XxZfOc6L5go8EJIueY",
    "Amount": "807.33000000",
    "AttendeeCount" :"0",
    "Custom1": "dfg",
    "Custom2": "7686",
    "Custom3": "89080990-90-5464",
    "Custom4": "56sdsd sf",
    "Custom5": null
  },
  {
    "AttendeeID": "nFaAj0ncBso0sBd8ejqrxLHz1FfmhJ69b",
    "Amount": "707.33000000",
    "AttendeeCount" :"0",
    "Custom1": "fg6rt",
    "Custom2": "9808",
    "Custom3": "64564drd",
    "Custom4": "352dsxcvs",
    "Custom5": null
  }
]

Example response

200 OK

GET Expense Entry Attendees

Retrieves the expense entry attendees for the specified expense entry. This function requires the v2.0 expense entry attendee resource.

Request

Parameters

Parameter Required/Optional Description
{_reportId_} Required The unique identifier for the expense report. This value is returned in the ReportID element by the Get Report Details function.
{_entryId_}/attendees Required The unique identifier for the expense entry and the Attendees keyword. This value is returned in the ReportEntryID element by the Get Report Details function.

Headers

Response

Headers

Payload

This request will return an Attendees parent element with an Attendee child element for each attendee. The Attendee element will have the following child elements.

Element Name Data Type Description
Amount decimal The portion of the Entry Transaction Amount assigned to this attendee.
AssociatedAttendeeCount int The count of attendees associated to this attendee. A count greater than 1 means there are unnamed attendees associated with this attendee.
AttendeeID string The unique identifier for the attendee.
EntryAttendeeCustom1 string The value for Entry-Attendee custom fields 1-5. Varies based on configuration.
EntryAttendeeCustom2 string The value for Entry-Attendee custom fields 1-5. Varies based on configuration.
EntryAttendeeCustom3 string The value for Entry-Attendee custom fields 1-5. Varies based on configuration.
EntryAttendeeCustom4 string The value for Entry-Attendee custom fields 1-5. Varies based on configuration.
EntryAttendeeCustom5 string The value for Entry-Attendee custom fields 1-5. Varies based on configuration.

Examples

XML example request

GET https://www.concursolutions.com/api/expense/expensereport/v2.0/report/nxxKgLlnROz3zHJBCRksaas23dsfs/entry/n7We3qWw99u1KoWTMaLhSC$pXBYzQ1UDhn/attendees HTTP/1.1
Authorization: OAuth {access token}

JSON example request

GET https://www.concursolutions.com/api/expense/expensereport/v2.0/report/nxxKgLlnROz3zHJBCRksaas23dsfs/entry/n7We3qWw99u1KoWTMaLhSC$pXBYzQ1UDhn/Attendees HTTP/1.1
Authorization: OAuth {access token}

XML example response

HTTP/1.1 200 OK
Content-Type: application/xml
<EntryAttendees xmlns="http://www.concursolutions.com/api/expense/expensereport/2012/07" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
  <Attendee>
    <Amount>2422.00000000</Amount>
    <AssociatedAttendeeCount>1</AssociatedAttendeeCount>
    <AttendeeID>nFaAj0ncBso0sBd8ejqrxLHz1FfmhJ69b</AttendeeID>
    <EntryAttendeeCustom1>Medical</EntryAttendeeCustom1>
    <EntryAttendeeCustom2>North America</EntryAttendeeCustom2>
    <EntryAttendeeCustom3>Canada</EntryAttendeeCustom3>
    <EntryAttendeeCustom4>Vancouver</EntryAttendeeCustom4>
    <EntryAttendeeCustom5 i:nil="true"/>
  </Attendee>
</EntryAttendees>

JSON example response

HTTP/1.1 200 OK
Content-Type: application/json
[
  {
    "AttendeeID": "nFaAj0ncBs$puDs5XxZfOc6L5go8EJIueY",
    "Amount": "807.33000000",
    "AttendeeCount": "0",
    "Custom1": "Medical",
    "Custom2": "North America",
    "Custom3": "Canada",
    "Custom4": "Vancouver",
    "Custom5": null
  },
  {
    "AttendeeID": "nFaAj0ncBso0sBd8ejqrxLHz1FfmhJ69b",
    "Amount": "707.33000000",
    "AttendeeCount": "0",
    "Custom1": "Medical",
    "Custom2": "North America",
    "Custom3": "Canada",
    "Custom4": "Vancouver",
    "Custom5": null
  }
]

Expense Group Configurations v1.1

This API has been deprecated.

Partners and customers using a deprecated API should contact SAP Concur and discuss moving to the latest versions.

Learn more in the API Lifecycle & Deprecation Policy.

The Expense Group Configuration contains the list of Expense Polices, Expense Types and Payment Types for the Expense Group the user specified in the OAuth access token is assigned to.

Resource URI

https://www.concursolutions.com/api/expense/expensereport/v1.1/ExpenseGroupConfiguration/

Get an expense group configuration

Retrieves the list of Expense Polices, Expense Types and Payment Types for the Expense Group the user specified in the OAuth access token is assigned to. Each Expense Policy contains a list of valid Expense Types. The Payment Types are associated with the user's Expense Group and apply to all the returned policies. Only the payment types that are valid for the Post Expense Entry endpoint are returned.

NOTE: The Concur Expense product is highly configurable, and each client may have a unique set of payment types. If a payment type is not included in the response, it is not available for use with this client.

Request

Parameters

None

Headers

Response

Payload

This request will return an ExpenseGroupConfiguration parent element. The ExpenseGroupConfiguration has a PaymentTypes child element and a PolicyAndExpenseTypesList child element.

The PaymentTypes child element has a PaymentType child element for each configured payment type. The PolicyAndExpenseTypesList child element has a PolicyandExpenseTypes child element for each policy configured for this expense group.

PaymentType elements

Element Description
PaymentTypeID The encrypted key for the payment type. This is the unique identifier for the payment type.
PaymentTypeName The name of the payment type.

PolicyandExpenseTypes elements

Element Description
PolicyKey The ID value of the policy.
PolicyName The name of the policy.
ExpenseTypes The parent element for the list of expense types in the policy. It contains an ExpenseType child element for each expense type in the policy.

ExpenseType elements

Element Description
ExpKey The expense type key.
ExpName The label of the expense type.
ParentExpKey The code of the expense type's parent.
ParentExpName The label of the expense type's parent.
SpendCategory The spend category assigned to the expense type for reporting purposes.

Examples

XML example request

GET https://www.concursolutions.com/api/expense/expensereport/v1.1/ExpenseGroupConfiguration/ HTTP/1.1
Authorization: OAuth {access token}

XML example of successful response

HTTP/1.1 200 OK
Content-Type: application/xml
<ExpenseGroupConfiguration xmlns="http://www.concursolutions.com/api/expense/expensereport/2011/03" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
  <PaymentTypes>
    <PaymentType>
      <PaymentTypeID>nr74tQrD8PorkF6yvS0Sm8ZeSGsw</PaymentTypeID>
      <PaymentTypeName>Cash</PaymentTypeName>
    </PaymentType>
    <PaymentType>
      <PaymentTypeID>nr7AuTtrvkXwLOzEejFruFO$sN7eo</PaymentTypeID>
      <PaymentTypeName>Company Paid</PaymentTypeName>
    </PaymentType>
  </PaymentTypes>
  <PolicyAndExpenseTypesList>
    <PolicyAndExpenseTypes>
      <PolicyKey>ndrF8hjzl9FhH1Lvs0EuK1gi7LISbetxc</PolicyKey>
      <PolicyName>CA Expense Policy</PolicyName>
      <ExpenseTypes>
        <ExpenseType>
          <ExpKey>BUSPR</ExpKey>
          <ExpName>Promotional Items</ExpName>
          <ParentExpKey>PROMO</ParentExpKey>
          <ParentExpName>Business Promotions</ParentExpName>
        </ExpenseType>
        <ExpenseType>
          <ExpKey>TRDSH</ExpKey>
          <ExpName>Trade Shows</ExpName>
          <ParentExpKey>PROMO</ParentExpKey>
          <ParentExpName>Business Promotions</ParentExpName>
        </ExpenseType>
        <ExpenseType>
          <ExpKey>LOCPH</ExpKey>
          <ExpName>Local Phone</ExpName>
          <ParentExpKey>COMMU</ParentExpKey>
          <ParentExpName>Communications</ParentExpName>
        </ExpenseType>
      </ExpenseTypes>
    </PolicyAndExpenseTypes>
  </PolicyAndExpenseTypesList>
</ExpenseGroupConfiguration>

Expense Report Header v1.1

This API has been deprecated.

Partners and customers using a deprecated API should contact SAP Concur and discuss moving to the latest versions.

NOTE: Find the newer version 3.0 here.

The expense report header contains classification information for the expense report, and serves as the container for the expense entries.

Resource URI

https://www.concursolutions.com/api/expense/expensereport/v1.1/report/

Post an expense report header

Posts the expense report header information for a new or existing report for the user specified in the OAuth access token. If the OAuth consumer has the necessary roles, they can update reports that belong to other users. Use this function to create a report, then use the Post Expense Entry function to send expense line items.

NOTES:

Request

Parameters

Parameter Required/Optional Description
{_reportId_} Optional The unique identifier for the report. Only used when updating an existing report.

Example:

https://www.concursolutions.com/api/expense/expensereport/v1.1/report/{reportId}

URI Source: The reportId value is returned by the Get List of Reports and Get Report Details functions, and as part of the Report-Details-Url element returned by this function.

Headers

The Concur user must have one of the following roles in Expense:

Payload

This request should contain a Report parent element with the following child elements.

Element Required (must contain value)? Description
Name Y The expense report name.
Purpose Depends on configuration The business purpose of the report. Maximum length: 500.
Comment Depends on configuration The report header comment. Maximum length: 500.
OrgUnit1 through OrgUnit6 Depends on configuration The custom Organization Unit fields. May be required depending on configuration. Refer to the Processes > Post Expense Report Data section of Expense Report for the steps necessary to gather required field information.
Custom1 through Custom20 Depends on configuration The custom fields on the Expense Report Header form. May be required depending on configuration. Refer to the Processes > Post Expense Report Data section of Expense Report for the steps necessary to gather required field information.
NOTE: If any of the custom fields are configured to contain list values, refer to the Posting Custom List Items page for information on how to correctly submit list item values.
UserDefinedDate Depends on configuration The date the user selected for the report. Format: YYYY-MM-DD hh:mm:ss.0

Response

Headers

Payload

The response will include a ReportDetails parent element. This element will contain a ReportStatus child element. The ReportStatus element will contain the following child elements.

Element Description
Status The status of the request.
Report-Details-Url The URI to use when posting report details to this report.

Examples

XML example of new report request

POST https://www.concursolutions.com/api/expense/expensereport/v1.1/report HTTP/1.1
Authorization: OAuth {access token}
Content-Type: application/xml
<Report xmlns="http://www.concursolutions.com/api/expense/expensereport/2011/03">
  <Name>January Expenses</Name>
  <Purpose>All expenses for January</Purpose>
  <Comment>Includes Client Meetings.</Comment>
  <OrgUnit1>US</OrgUnit1>
  <OrgUnit2>NW</OrgUnit2>
  <OrgUnit3>Redmond</OrgUnit3>
  <Custom1>Client</Custom1>
  <Custom2>Local</Custom2>
  <UserDefinedDate>2011-03-26 15:15:07.0</UserDefinedDate>
</Report>

XML example of successful response

HTTP/1.1 200 OK
Content-Type: application/xml
<ReportDetails>
  <ReportStatus xmlns="http://www.concursolutions.com/api/expense/expensereport/2011/03" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
    <Status>SUCCESS</Status>
    <Report-Details-Url>https://www.concursolutions.com/api/expense/expensereport/v1.1/report/nxxKgLlnRODp$sie8Hq1UviOJ2AbpS7dCP</Report-Details-Url>
  </ReportStatus>
</ReportDetails>

Post Report Header Batch Request

Posts a batch of expense report headers. The expense report header contains classification information for the expense report. Use this endpoint to create a batch of reports, then use the Post Expense Entry function to send expense line items. All batch operations allow up to 1000 headers per batch. If a batch request with over 1000 headers is sent, only the first 1000 headers in the batch will be processed.
NOTE: Posting expense report information is a multi-stage process. Refer to the Processes  section of the Expense Report Web Service page for the steps required to post new expense reports and entries.

Request

Parameters

Parameter Required/Optional Description
batch required The batch keyword.

Example:

https://www.concursolutions.com/api/expense/expensereport/v1.1/report/batch

Headers

The Concur user must have one of the following roles in Expense:

Payload

This request should contain a batch parent element with a Report parent element for each included report. The Report element contains the following child elements.

Report elements
Element Required (must contain value)? Description
Index Y The header's location in the batch. Should start at 1 and increment sequentially. This value is used to identify the record if there is an error.
LoginId Y The report owner's Concur login ID.
Name Y The expense report name.
Purpose Depends on configuration The business purpose of the report. Maximum length: 500.
Comment Depends on configuration The report header comment. Maximum length: 500.
OrgUnit1 through OrgUnit6 Depends on configuration The custom Organization Unit fields. May be required depending on configuration. Refer to the Processes > Post Expense Report Data section of Expense Report for the steps necessary to gather required field information.
Custom1 through Custom20 Depends on configuration The custom fields on the Expense Report Header form. May be required depending on configuration. Refer to the Processes > Post Expense Report Data section of Expense Report for the steps necessary to gather required field information.
NOTE: If any of the custom fields are configured to contain list values, please refer to the Posting Custom List Items page for information on how to correctly submit list item values.
UserDefinedDate Depends on configuration The date the user selected for the report. Format: YYYY-MM-DD hh:mm:ss.0

Response

Headers

Payload

This request will return a report-batch-result parent element with the following child elements.

Element Description
records-succeeded The number of records processed that were successfully added.
records-failed The number of records processed that were not successfully added.
errors This will contain an error parent element for each record failure. For details about the error child elements, see the error child elements table below.
ReportDetails This parent element will contain a ReportStatus child element for all report headers that did not cause an error. For details about the ReportStatus child elements, see the ReportStatus child elements table below.

error elements

Element Description
Index The header's location in the batch
LoginID The user's Concur login ID.
message The error message.

ReportStatus elements

Element Description
Status The status of the request.
Report-Details-Url The URI to use when posting report details to this report.

Examples

XML example request

POST https://www.concursolutions.com/api/expense/expensereport/v1.1/report/batch HTTP/1.1
Authorization: OAuth {access token}
Content-Type: application/xml
<batch xmlns="http://www.concursolutions.com/api/expense/expensereport/2011/03">
  <Report>
    <Index>1</Index>
    <LoginId>cmiller@example.com</LoginId>
    <Name>January Expenses</Name>
    <Purpose>All expenses for January</Purpose>
    <Comment>Includes Client Meetings.</Comment>
    <OrgUnit1>US</OrgUnit1>
    <OrgUnit2>NW</OrgUnit2>
    <OrgUnit3>Redmond</OrgUnit3>
    <Custom1>Client</Custom1>
    <Custom2>Local</Custom2>
    <UserDefinedDate>2011-01-26 12:15:00.0</UserDefinedDate>
  </Report>
  <Report>
    <Index>2</Index>
    <LoginId>tbrown@example.com</LoginId>
    <Name>Trip to New York </Name>
    <Purpose>New York Sales Meeting </Purpose>
    <Comment></Comment>
    <OrgUnit1>US</OrgUnit1>
    <OrgUnit2></OrgUnit2>
    <OrgUnit3>Tucson</OrgUnit3>
    <Custom1>Client</Custom1>
    <Custom2>Remote</Custom2>
    <UserDefinedDate>2011-02-04 15:25:07.0</UserDefinedDate>
  </Report>
</batch>

XML example response with success and failure

HTTP/1.1 200 OK
Content-Type: application/xml
<report-batch-result xmlns="http://www.concursolutions.com/api/expense/expensereport/2011/03" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
  <records-succeeded>1</records-succeeded>
  <records-failed>1</records-failed>
  <errors>
    <error>
      <Index>2</Index>
      <LoginID>tbrown@example.com</LoginID>
      <message>Invalid Value for:OrgUnit2</message>
    </error>
  </errors>
  <ReportDetails>
    <ReportStatus >
      <Index>1</Index>
      <Status>SUCCESS</Status>
      <Report-Details-Url>https://www.concursolutions.com/api/expense/expensereport/v1.1/nxxKgLlnRODp$sie8Hq1UviOJ2AbpS7dCP</Report-Details-Url>
    </ReportStatus>
  </ReportDetails>
</report-batch-result>

Expense Reports List v1.1

This API has been deprecated.

Partners and customers using a deprecated API should contact SAP Concur and discuss moving to the latest versions.

Learn more in the API Lifecycle & Deprecation Policy.

Get list of expense reports

Retrieves a list of reports. This endpoint can be used to view reports for one user, or to view recent reports for the entire company. If you get reports for one user, you can view reports owned by the user specified in the OAuth access token. If you choose to get all the reports for the company, you must use the LastModified date query string to view reports for a 24 hour period. You can provide an optional View to target search results. If no view or date string is provided, the web service will return all Recent reports for the specified user. If the LastModified query string is provided, the results do not filter based on the specified user. This endpoint can support frequent requests, where the developer tracks the previous date/time that the endpoint was called, and uses that as the date/time for the next request.

Request

URI

GET https://www.concursolutions.com/api/expense/expensereport/v1.1/ReportsList/{_View_}

Parameters

This URI can be appended with the following optional report View values:

Value Description
RECENT Returns all reports that have been modified in the last 31 days for the specified user.
ACTIVE Returns all unsubmitted and unpaid (payment status is not Paid) reports for the specified user.
UNSUBMITTED Returns all unsubmitted reports for the specified user.
PENDING Returns all pending reports for the specified user.
APPROVED Returns all approved reports for the specified user.
PROCESSED Returns all processed reports for the specified user.
PAID Returns all paid reports for the specified user.
PAYMENTCONFIRMED Returns all paid reports for the specified user.
FORTHISMONTH Returns all reports with a create date in this month by the specified user.
FORLASTMONTH Returns all reports with a create date in the previous month by the specified user.
FORTHISQUARTER Returns all reports with a create date in this calendar quarter by the specified user.
FORLASTQUARTER Returns all reports with a create date in the previous calendar quarter by the specified user.
FORTHISYEAR Returns all reports with a create date in this year by the specified user.
FORLASTYEAR Returns all reports with a create date in in the past year by the specified user.
TOAPPROVE Returns all reports pending approval from the specified user.
APPROVEDTHISMONTH Returns all reports approved or pending approval from the specified user in the current month.
APPROVEDLASTMONTH Returns all reports approved by the specified user in the current month.
APPROVEDTHISQUARTER Returns all reports approved or pending approval from the specified user in the current calendar quarter.
APPROVEDLASTQUARTER Returns all reports approved by the specified user in the previous calendar quarter.
APPROVEDTHISYEAR Returns all reports approved or pending approval from the specified user in the current calendar year.
APPROVEDLASTYEAR Returns all reports approved by the specified user in the previous calendar year.

This request can include an optional query string specifying the last modified date (in Coordinated Universal Time, aka UTC) of the reports. This query string will return the reports modified within 24 hours after the supplied date. You can provide the time in UTC, and the query will return the reports with a last modified date that is greater (up to 24 hours after the time) or equal to the supplied time. The provided date/time can be any time between now and the first date of expense report creation in the database. The format is either the date or the date and time combined:

/api/expense/expensereport/v1.1/reportslist/UNSUBMITTED/LastModified?date=2011-07-06T12:23:00

or

/api/expense/expensereport/v1.1/reportslist/UNSUBMITTED/LastModified?date=2011-07-06

The LastModified query string is supported only with the following statuses: ALL, ACTIVE, UNSUBMITTED, APPROVED, PENDING, PROCESSED, PAID, PAYMENTCONFIRMED, RECENT, TOAPPROVE

NOTES:

Headers

Response

Headers

Payload

This request will return a ReportsList parent element with an xmlns version attribute and a ReportSummary child element for each report. The ReportSummary elements will have the following child elements:

Value Description
ApprovalURL The URL the user can use to log in to Concur to approve the report. This element appears when requesting the TOAPPROVE status, and does not appear when using the DateModified query. This URL works only when the company does not use Concur SSO with the Enforce option.
ReportName The name of the report.
ReportId The unique identifier for the report, which appears in the Concur Expense UI.
ReportTotal The total amount of the report.
ReportCurrency The 3-letter ISO 4217 currency code for the expense report currency.
ReportDate The create date of the report.
LastComment The text of the most recent comment on the report.
Report-Details-Url The URL to access the report summary details.
Report-Full-Details-Url The URL to access the full report details.
ExpenseUserXUserID The User ID of the user this report belongs to.
ApproverXUserID The User ID of the user's expense approver.
EmployeeName The name of the expense report owner. Format: Firstname Lastname

Notes:

The ApprovalURL provides a link to Expense that can be used with SSO in most circumstances. The link can be put into a browser window, then the approver is automatically logged into Expense and the expense report opens if:

Otherwise, when the approver clicks the link, the Expense login page appears. The approver logs in and follows the normal steps for approving reports.

Report Full Details v1.1

This API has been deprecated.

Partners and customers using a deprecated API should contact SAP Concur and discuss moving to the latest versions.

Learn more in the API Lifecycle & Deprecation Policy.

Retrieves the full set of information for the report. Includes the Report Header, Entry, Attendee, Itemization and Allocation details.

Get expense report full details

Request

URI

This URI is returned in the Report-Full-Details-Url element by the Expense Reports List v1.1 endpoint. The report key is the encrypted database key for the report.

GET https://www.concursolutions.com/api/expense/expensereport/v1.1/reportfulldetails/_{reportKey}_

Headers

Response

Headers

Payload

This request will return a <ReportDetails> parent element with an xmlns version attribute and the following child elements:

Element Description
X-UserID The user ID of the report owner.
ReportId The unique identifier for the report, which appears in the Concur Expense UI.
ReportName The name of the report.
Purpose The information from the Business Purpose field.
CrnCode The 3-letter ISO 4217 currency code for the expense report currency. The expense report currency is defined as the report creator's default reimbursement currency.
ApsKey The approval status code for the report.
ReportDate The date from the report header. Format: YYYY-MM-DDThh:mm:ss
CreationDate The date the report was created. Format: YYYY-MM-DDThh:mm:ss
ReceiptImageUrl The URL to access the image associated with the report. This URL is only valid for 30 minutes after the web service call.
HasException Whether the report has exceptions. Format: Y/N
EverSentBack Whether the report has ever been sent back to the employee. Format: Y/N
EmployeeName The name of the employee who created the report.
ApvStatusName The approval status name for the report.
PayKey The unique identifier for the payment status of the report.
PayStatusName The payment status of the report.
PaidDate The date the report was extracted for payment. This element has an attribute named i:nil. If the value for this element is null, the i:nil attribute will be set to true. Format: YYYY-MM-DDThh:mm:ss
SubmitDate The date the report was submitted.
EntryCount The number of expense entries in the report. This count includes itemized entries.
LedgerName The name of the expense report ledger.
OrgUnit1 through OrgUnit6 The details from the Org Unit custom fields. These may not have data, depending on configuration.
Custom1 through Custom20 The details from the Custom fields. These may not have data, depending on configuration. If the custom field is a list field, the data will be returned as: (list item short code) list item name. List Field Example: (1234) Project 1234</Custom1
PolKey The unique identifier of the policy that applies to this report.
RptKey The encrypted database key for the report, which is used as the unique identifier in other web service requests.
ReportTotal The total amount of the report.
PersonalExpenses The total amount of expenses marked as personal.
AmountDueEmployee The total amount due to the employee for the report.
AmountDueCompanyCard The total amount due to the company card for the report.
TotalClaimedAmount The total amount of all non-personal expenses in the report.
TotalApprovedAmount The total amount of approved expenses in the report.
WorkflowActionURL The URL to post a workflow action to the report using the Post Report Workflow Action endpoint.
Entries This parent element has a Count attribute indicating the number of entries (not including itemization entries) that are included in the report. It has an ExpenseEntry child element for each entry. Refer to the Expense Entry Child Elements table for more information.

Expense Entry Child Elements

Element Description
ReceiptRequired Whether the original receipt is required for the entry.
ImageRequired Whether a receipt image is required for the entry.
EreceiptId The ID for the attached e-receipt, if available.
Custom1 through Custom40 The details from the Custom fields. These may not have data, depending on configuration. If the custom field is a list field, the data will be returned as: (list item short code) list item name. List Field Example: (1234) Project 1234</Custom1
RpeKey The ID of the report entry.
RptKey The encrypted database key of the report.
ExpKey The expense type key for the expense entry. Expense Type Keys are returned in the ExpKey element by the Expense Group Configuration endpoint.
FormKey The key for the expense entry form.
ReceiptImageId The unique identifier for the image associated with the entry.
ExpName The expense type name.
SpendCategory The spend category specified for this expense type. Varies by client, used in reporting.
BusinessPurpose The text from the Business Purpose field of the entry.
HasVat Whether the entry contains VAT data.
ExchangeRate The exchange rate that applies to the entry.
TransactionAmount The amount of the expense entry in the original transaction currency.
PostedAmount The amount of the expense entry in the user's reimbursement currency. The user's reimbursement currency is returned in the <CrnCode element for the report.
ApprovedAmount The approved amount of the expense entry in the user's reimbursement currency. The user's reimbursement currency is returned in the <CrnCode element for the report.
TransactionCurrencyName The name of the transaction currency.
VendorDescription The vendor name of the expense entry, which can be entered manually by the user or imported from the card transaction Merchant Name field.
LocationName The location for the expense entry, usually the city name.
LocationSubdivision The location's State, Province, or Country Subdivision.
LocationCountry The location's Country.
OrgUnit1 through OrgUnit6 The details from the Org Unit custom fields. These may not have data, depending on configuration.
HasComments Whether the expense entry has comments.
CommentCount The number of comments associated with the expense entry.
PaymentTypeKey The key for the payment type.
IsItemized Whether the expense entry is itemized.
HasExceptions Whether the expense entry has exceptions.
IsPersonal Whether the expense entry is marked as personal.
HasAttendees Whether the expense entry has attendees.
HasAllocation Defines the amount of allocations for the expense. Possible values are: P, for partial allocation, F, for full allocation, or N, for no allocation.
IsCreditCardCharge Whether the expense came from a credit card feed.
AttendeeCount The number of attendees associated with the expense entry.
IsPersonalCardCharge Whether the expense came from a personal card feed.
TransactionDate The date of the expense entry.
LastModifiedDate The date the expense entry was last changed.
ItemizationList The list of itemizations for the expense entry. This parent element is empty if there are no itemizations. When the report has itemizations, this element contains an ItemizationEntry Details element for each itemization. Refer to the Itemization Entry Details Child Elements table for more information.

Itemization Entry Details Child Elements

Element Description
Custom1 through Custom40 The custom fields associated with the itemization. These may not have data, depending on your configuration. If the custom field is a list field, the data will be returned as: (list item short code) list item name. List Field Example: (1234) Project 1234
ItemizationKey The unique identifier for the itemization.
ExpenseKey The expense type key for the itemization.
ExpenseName The expense type for the itemization.
BusinessPurpose The business purpose field from the report header.
TransactionAmount The amount for the itemization in the expense currency.
TransactionDate The date of the transaction.
PostedAmount The amount for the itemization in the user's reimbursement currency. The user's reimbursement currency is returned in the <CrnCode element for the report.
ApprovedAmount The approved amount of the itemization in the user's reimbursement currency. The user's reimbursement currency is returned in the <CrnCode element for the report.
HasComments Whether the itemization has comments.
IsPersonal Whether the itemization is personal.
LastModified The UTC date when the itemization was last modified.
AllocationsList This parent element contains one Allocations element for each associated allocation. This element will be empty if there are no allocations. The parent element contains child elements
Allocations This element appears once for each allocation associated with the expense entry if the entry is not itemized. This element will be empty if there are no allocations, or if the ItemizationList element contains the allocation data. This element contains child elements.
AttendeeDetails This parent element appears once for each associated attendee, and contains child elements.

Allocations List Child Elements

Element Description
Custom1 through Custom20 The custom fields associated with the allocation. These may not have data, depending on your configuration. If the custom field is a list field, the data will be returned as: (list item short code) list item name. List Field Example: (1234) Project 1234
AllocationKey The unique alphanumeric identifier for the allocation.
Percentage The percentage of the expense that is included in this allocation.
AccountCode1 The account code for the allocation.
AccountCode2 The second account code for the allocation. This is only populated in rare cases, such as when using travel allowance, where one expense might have an account code for the allowed amount, and a second account code for the overage.

Allocations Child Elements

Element Description
Custom1 through Custom20 The custom fields associated with the allocation. These may not have data, depending on your configuration. If the custom field is a list field, the data will be returned as: (list item short code) list item name. List Field Example: (1234) Project 1234
AccountCode1 The account code for the allocation.
AccountCode2 The second account code for the allocation. This is only populated in rare cases, such as when using travel allowance, where one expense might have an account code for the allowed amount, and a second account code for the overage.
allocKey The unique alphanumeric identifier for the allocation.
percentage The percentage of the expense that is included in this allocation.

Attendee Details Child Elements

Element Description
Custom1 through Custom20 The details from the Custom fields. These may not have data, depending on configuration. If the custom field is a list field, the data will be returned as
AttendeeType The type of attendee.
FirstName The attendee's first name.
LastName The attendee's last name.
Company The attendee's company name.
ExternalId The unique identifier for the attendee, managed outside Concur.
HasExceptionsPrevYear Whether the attendee has exceptions in the previous year, based on yearly total limits for attendees.
HasExceptionsYtd Whether the attendee has exceptions in the current year, based on yearly total limits for attendees.
IsDeleted Whether the attendee is marked as deleted.
OwnerEmpName The name of the employee that owns the attendee record.
Title The attendee's title.
TotalAmountPrevYear The total amount spent on the attendee in the previous calendar year.
TotalAmountYtd The total amount spent on the attendee in the current calendar year.
VersionNumber The attendee's version number.
AttendeeKey Attendee unique identifier within Concur.

Example

Request

GET http://www.concursolutions.com/api/expense/expensereport/v1.1/reportfulldetails/n6ujbuLd1Arwe45lT7As3ThJYJf2dAsrrEW HTTPS/1.1
Host: www.concursolutions.com
Authentication: OAuth

Response

HTTPS/1.1 200 OK
Content-Type: application/xml
<ReportDetails xmlns:ns="http://www.concursolutions.com/api/expense/expensereport/2011/03" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
  <X_UserID>cmiller@example.com</X_UserID>
  <ReportId>4681D8C33A284E91A46E</ReportId>
  <ReportName>Client Meeting </ReportName>
  <Purpose>Sales meeting</Purpose>
  <CrnCode>USD</CrnCode>
  <ApsKey>A_NOTF</ApsKey>
  <ReportDate>2011-05-12T00:00:00</ReportDate>
  <CreationDate>2011-05-12T14:15:36</CreationDate>
  <ReceiptImageUrl>http://www.concursolutions.com/getImage?cid=p0000002tcnl&amp;val=D9EC86BB902B8D48</ReceiptImageUrl>
  <HasException>N</HasException>
  <EverSentBack>N</EverSentBack>
  <EmployeeName>Miller, Chris </EmployeeName>
  <ApvStatusName>Not Submitted</ApvStatusName>
  <PayKey>P_NOTP</PayKey>
  <PayStatusName>Not Paid</PayStatusName>
  <PaidDate i:nil="true"/>
  <SubmitDate>0001-01-01T00:00:00</SubmitDate>
  <EntryCount>2</EntryCount>
  <LedgerName>DEFAULT</LedgerName>
  <OrgUnit1 />
  <OrgUnit2 />
  <OrgUnit3 />
  <OrgUnit4 />
  <OrgUnit5 />
  <OrgUnit6 />
  <Custom1 />
  <Custom2 />
  <Custom3 />
  <Custom4 />
  <Custom5 />
  <Custom6 />
  <Custom7 />
  <Custom8 />
  <Custom9 />
  <Custom10 />
  <Custom11 />
  <Custom12 />
  <Custom13 />
  <Custom14 />
  <Custom15 />
  <Custom16 />
  <Custom17 />
  <Custom18 />
  <Custom19 />
  <Custom20 />
  <PolKey>n3VIbuLd1AU4tlT7As3ThJYJf2dADsJ1V</PolKey>
  <RptKey>n6ujbuLd1Arwe45lT7As3ThJYJf2dAsrrEW</RptKey>
  <ReportTotal>129.00000000</ReportTotal>
  <PersonalExpenses>0.00000000</PersonalExpenses>
  <AmountDueEmployee>129.00000000</AmountDueEmployee>
  <AmountDueCompanyCard>0.00000000</AmountDueCompanyCard>
  <TotalClaimedAmount>129.00000000</TotalClaimedAmount>
  <TotalApprovedAmount>129.00000000</TotalApprovedAmount>
  <WorkflowActionURL>http://www.concursolutions.com/api/expense/expensereport/v1.1/report/Ko9%t8GHpERQVpk$pS2EL6EDHRwi9r$paQS1UqyL6a454QitqQ/WorkFlowAction</WorkflowActionURL>
  <Entries Count="2">
    <ExpenseEntry>
      <ReceiptRequired>N</ReceiptRequired>
      <ImageRequired>Y</ImageRequired>
      <EreceiptId />
      <OrgUnit1 />
      <OrgUnit2 />
      <OrgUnit3 />
      <OrgUnit4 />
      <OrgUnit5 />
      <OrgUnit6 />
      <Custom1 />
      <Custom2 />
      <Custom3 />
      <Custom4 />
      <Custom5 />
      <Custom6 />
      <Custom7 />
      <Custom8 />
      <Custom9 />
      <Custom10 />
      <Custom11 />
      <Custom12 />
      <Custom13 />
      <Custom14 />
      <Custom15 />
      <Custom16 />
      <Custom17 />
      <Custom18 />
      <Custom19 />
      <Custom20 />
      <Custom21 />
      <Custom22 />
      <Custom23 />
      <Custom24 />
      <Custom25 />
      <Custom26 />
      <Custom27 />
      <Custom28 />
      <Custom29 />
      <Custom30 />
      <Custom31 />
      <Custom32 />
      <Custom33 />
      <Custom34 />
      <Custom35 />
      <Custom36 />
      <Custom37 />
      <Custom38 />
      <Custom39 />
      <Custom40 />
      <RpeKey>nfUEGTNhWxbXkeT26XlVm9Gdqvbi8hlDa</RpeKey>
      <RptKey>nbe1LDA99RdTx0fUEuZiYd5WW8afkjew$p</RptKey>
      <X_UserID>cmiller@example.com</X_UserID>
      <ExpKey>BUSMEAL</ExpKey>
      <FormKey>nnamf5z0cLe4MHs53YwSIjwY0uP8kby5p</FormKey>
      <ReceiptImageId />
      <ExpName>BUSMEAL</ExpName>
      <BusinessPurpose />
      <HasVat>N</HasVat>
      <ExchangeRate>1.00000000000000</ExchangeRate>
      <TransactionAmount>115.00000000</TransactionAmount>
      <PostedAmount>115.00000000</PostedAmount>
      <ApprovedAmount>115.00000000</ApprovedAmount>
      <TransactionCurrencyName>Dollar, United States</TransactionCurrencyName>
      <VendorDescription>Mel's Diner </VendorDescription>
      <LocationName>Seattle</LocationName>
      <LocationSubdivision>WA</LocationSubdivision>
      <LocationCountry>US</LocationCountry>
      <SpendCategory>Meals and Entertainment</SpendCategory>
      <HasComments>N</HasComments>
      <CommentCount>0</CommentCount>
      <PaymentTypeKey>CASH</PaymentTypeKey>
      <IsItemized>Y</IsItemized>
      <HasExceptions>N</HasExceptions>
      <IsPersonal>N</IsPersonal>
      <HasAttendees>Y</HasAttendees>
      <HasAllocation>Y</HasAllocation>
      <IsCreditCardCharge>N</IsCreditCardCharge>
      <AttendeeCount>2</AttendeeCount>
      <IsPersonalCardCharge>N</IsPersonalCardCharge>
      <TransactionDate>2011-05-19T00:00:00</TransactionDate>
      <LastModifiedDate>2011-05-19T14:44:50</LastModifiedDate>
      <ItemizationsList>
        <ItemizationEntryDetails>
          <Custom1 />
          <Custom2 />
          <Custom3 />
          <Custom4 />
          <Custom5 />
          <Custom6 />
          <Custom7 />
          <Custom8 />
          <Custom9 />
          <Custom10 />
          <Custom11 />
          <Custom12 />
          <Custom13 />
          <Custom14 />
          <Custom15 />
          <Custom16 />
          <Custom17 />
          <Custom18 />
          <Custom19 />
          <Custom20 />
          <Custom21 />
          <Custom22 />
          <Custom23 />
          <Custom24 />
          <Custom25 />
          <Custom26 />
          <Custom27 />
          <Custom28 />
          <Custom29 />
          <Custom30 />
          <Custom31 />
          <Custom32 />
          <Custom33 />
          <Custom34 />
          <Custom35 />
          <Custom36 />
          <Custom37 />
          <Custom38 />
          <Custom39 />
          <Custom40 />
          <ItemizationKey>nE0avYnILN6vKNUGsh5lCg6vt$sqc9qB$sq</ItemizationKey>
          <ExpenseKey>MISCL</ExpenseKey>
          <ExpenseName>Miscellaneous</ExpenseName>
          <BusinessPurpose>Promo T-shirt</BusinessPurpose>
          <TransactionAmount>8.00000000</TransactionAmount>
          <TransactionDate>2011-05-19T00:00:00</TransactionDate>
          <PostedAmount>8.00000000</PostedAmount>
          <ApprovedAmount>8.00000000</ApprovedAmount>
          <HasComments>Y</HasComments>
          <CommentCount>0</CommentCount>
          <IsPersonal>N</IsPersonal>
          <LastModified>2011-05-19T14:06:53</LastModified>
          <AllocationsList>
            <Allocations>
              <Custom1>North America</Custom1>
              <Custom2>West</Custom2>
              <Custom3 />
              <Custom4 />
              <Custom5 />
              <Custom6 />
              <Custom7 />
              <Custom8 />
              <Custom9 />
              <Custom10 />
              <Custom11 />
              <Custom12 />
              <Custom13 />
              <Custom14 />
              <Custom15 />
              <Custom16 />
              <Custom17 />
              <Custom18 />
              <Custom19 />
              <Custom20 />
              <AllocationKey>ngYn5SB4OUXwHnBjh8$pBIT8oPxe9G$shCi</AllocationKey>
              <Percentage>100.00000000%</Percentage>
              <AccountCode1>MISC_EXP</AccountCode1>
              <AccountCode2 />
            </Allocations>
          </AllocationsList>
        </ItemizationEntryDetails>
        <ItemizationEntryDetails>
          <Custom1 />
          <Custom2 />
          <Custom3 />
          <Custom4 />
          <Custom5 />
          <Custom6 />
          <Custom7 />
          <Custom8 />
          <Custom9 />
          <Custom10 />
          <Custom11 />
          <Custom12 />
          <Custom13 />
          <Custom14 />
          <Custom15 />
          <Custom16 />
          <Custom17 />
          <Custom18 />
          <Custom19 />
          <Custom20 />
          <Custom21 />
          <Custom22 />
          <Custom23 />
          <Custom24 />
          <Custom25 />
          <Custom26 />
          <Custom27 />
          <Custom28 />
          <Custom29 />
          <Custom30 />
          <Custom31 />
          <Custom32 />
          <Custom33 />
          <Custom34 />
          <Custom35 />
          <Custom36 />
          <Custom37 />
          <Custom38 />
          <Custom39 />
          <Custom40 />
          <ItemizationKey>nE0avYnILN6hfJ8LSXF8Qd9WkOkwSp83G</ItemizationKey>
          <ExpenseKey>BRKFT</ExpenseKey>
          <ExpenseName>Breakfast</ExpenseName>
          <BusinessPurpose>Client Meeting</BusinessPurpose>
          <TransactionAmount>107.00000000</TransactionAmount>
          <TransactionDate>2011-05-19T00:00:00</TransactionDate>
          <PostedAmount>107.00000000</PostedAmount>
          <ApprovedAmount>107.00000000</ApprovedAmount>
          <HasComments>Y</HasComments>
          <CommentCount>0</CommentCount>
          <IsPersonal>N</IsPersonal>
          <LastModified>2011-05-19T14:06:33</LastModified>
          <AllocationsList>
            <Allocations>
              <Custom1>North America</Custom1>
              <Custom2>West</Custom2>
              <Custom3>Oregon</Custom3>
              <Custom4 />
              <Custom5 />
              <Custom6 />
              <Custom7 />
              <Custom8 />
              <Custom9 />
              <Custom10 />
              <Custom11 />
              <Custom12 />
              <Custom13 />
              <Custom14 />
              <Custom15 />
              <Custom16 />
              <Custom17 />
              <Custom18 />
              <Custom19 />
              <Custom20 />
              <AllocationKey>ngYn5SB4OUQfJtTrUBq94qWUuDk8g6fo$s</AllocationKey>
              <Percentage>50.00000000%</Percentage>
              <AccountCode1>MEAL_BRKFST</AccountCode1>
              <AccountCode2 />
            </Allocations>
            <Allocations>
              <Custom1>North America</Custom1>
              <Custom2>West</Custom2>
              <Custom3>Washington</Custom3>
              <Custom4 />
              <Custom5 />
              <Custom6 />
              <Custom7 />
              <Custom8 />
              <Custom9 />
              <Custom10 />
              <Custom12 />
              <Custom13 />
              <Custom14 />
              <Custom15 />
              <Custom16 />
              <Custom17 />
              <Custom18 />
              <Custom19 />
              <Custom20 />
              <AllocationKey>ngYn5SB4OUX$pWN0Y6bkzFZZhdQ2PJ$pc6b</AllocationKey>
              <Percentage>50.00000000%</Percentage>
              <AccountCode1>MEAL_BRKFST</AccountCode1>
              <AccountCode />
            </Allocations>
          </AllocationsList>
        </ItemizationEntryDetails>
      </ItemizationsList>
      <Allocations />
      <AttendeeDetails>
        <Custom1 />
        <Custom2 />
        <Custom3 />
        <Custom4 />
        <Custom5 />
        <Custom6 />
        <Custom7 />
        <Custom8 />
        <Custom9 />
        <Custom10 />
        <Custom11 />
        <Custom12 />
        <Custom13 />
        <Custom14 />
        <Custom15 />
        <Custom16 />
        <Custom17 />
        <Custom18 />
        <Custom19 />
        <Custom20 />
        <AttendeeType>SYSEMP</AttendeeType>
        <FirstName>Chris</FirstName>
        <LastName>Miller</LastName>
        <Company />
        <ExternalId />
        <HasExceptionsPrevYear>N</HasExceptionsPrevYear>
        <HasExceptionsYtd>N</HasExceptionsYtd>
        <IsDeleted>N</IsDeleted>
        <OwnerEmpName>Miller, Chris</OwnerEmpName>
        <Title />
        <TotalAmountPrevYear>0.00000000</TotalAmountPrevYear>
        <TotalAmountYtd>0.00000000</TotalAmountYtd>
        <VersionNumber>1</VersionNumber>
        <AttendeeKey>njxM6iDZutaiGWiqbak$sEciMQPevMSInD</AttendeeKey>
      </AttendeeDetails>
      <AttendeeDetails>
        <Custom1 />
        <Custom2 />
        <Custom3 />
        <Custom4 />
        <Custom5 />
        <Custom6 />
        <Custom7 />
        <Custom8 />
        <Custom9 />
        <Custom10 />
        <Custom11 />
        <Custom12 />
        <Custom13 />
        <Custom14 />
        <Custom15 />
        <Custom16 />
        <Custom17 />
        <Custom18 />
        <Custom19 />
        <Custom20 />
        <AttendeeType>BUSGUEST</AttendeeType>
        <FirstName>Pat</FirstName>
        <LastName>Davis</LastName>
        <Company>Medico</Company>
        <ExternalId />
        <HasExceptionsPrevYear>N</HasExceptionsPrevYear>
        <HasExceptionsYtd>N</HasExceptionsYtd>
        <IsDeleted>N</IsDeleted>
        <OwnerEmpName>Miller, Chris</OwnerEmpName>
        <Title>Finance Manager</Title>
        <TotalAmountPrevYear>0.00000000</TotalAmountPrevYear>
        <TotalAmountYtd>0.00000000</TotalAmountYtd>
        <VersionNumber>1</VersionNumber>
        <AttendeeKey>njxM6iDZpwahAX2jt$pdRQ1etD1lNzfW83</AttendeeKey>
      </AttendeeDetails>
    </ExpenseEntry>
    <ExpenseEntry>
      <ReceiptRequired>N</ReceiptRequired>
      <ImageRequired>Y</ImageRequired>
      <EreceiptId />
      <OrgUnit1 />
      <OrgUnit2 />
      <OrgUnit3 />
      <OrgUnit4 />
      <OrgUnit5 />
      <OrgUnit6 />
      <Custom1 />
      <Custom2 />
      <Custom3 />
      <Custom4 />
      <Custom5 />
      <Custom6 />
      <Custom7 />
      <Custom8 />
      <Custom9 />
      <Custom10 />
      <Custom11 />
      <Custom12 />
      <Custom13 />
      <Custom14 />
      <Custom15 />
      <Custom16 />
      <Custom17 />
      <Custom18 />
      <Custom19 />
      <Custom20 />
      <Custom21 />
      <Custom22 />
      <Custom23 />
      <Custom24 />
      <Custom25 />
      <Custom26 />
      <Custom27 />
      <Custom28 />
      <Custom29 />
      <Custom30 />
      <Custom31 />
      <Custom32 />
      <Custom33 />
      <Custom34 />
      <Custom35 />
      <Custom36 />
      <Custom37 />
      <Custom38 />
      <Custom39 />
      <Custom40 />
      <RpeKey>nfUEGTNhWxbQmRXziCxZr2FNJmJWOcx0G</RpeKey>
      <RptKey>nbe1LDA99RdTx0fUEuZiYd5WW8afkjew$p</RptKey>
      <ExpKey>TRDSH</ExpKey>
      <FormKey>nnamf5z0cLe4MHs53YwSIjwY0uP8kby5p</FormKey>
      <ReceiptImageId>6EA8D791D82231349763EFCBC1822318</ReceiptImageId>
      <ExpName>PARKING</ExpName>
      <HasVat>N</HasVat>
      <ExchangeRate>1.00000000000000</ExchangeRate>
      <TransactionAmount>14.00000000</TransactionAmount>
      <PostedAmount>14.00000000</PostedAmount>
      <ApprovedAmount>14.00000000</ApprovedAmount>
      <TransactionCurrencyName>US, Dollar</TransactionCurrencyName>
      <VendorDescription>Saf-T-Park</VendorDescription>
      <LocationName />
      <LocationSubdivision />
      <LocationCountry />
      <SpendCategory>Transportation</SpendCategory>
      <HasComments>N</HasComments>
      <CommentCount>0</CommentCount>
      <PaymentTypeKey>CASH</PaymentTypeKey>
      <IsItemized>N</IsItemized>
      <HasExceptions>N</HasExceptions>
      <IsPersonal>N</IsPersonal>
      <HasAttendees>N</HasAttendees>
      <HasAllocation>N</HasAllocation>
      <IsCreditCardCharge>N</IsCreditCardCharge>
      <AttendeeCount>0</AttendeeCount>
      <IsPersonalCardCharge>N</IsPersonalCardCharge>
      <TransactionDate>2011-05-19T00:00:00</TransactionDate>
      <LastModifiedDate>2011-05-26T20:22:03</LastModifiedDate>
      <ItemizationList />
      <Allocations>
        <Custom1 />
        <Custom2 />
        <Custom3 />
        <Custom4 />
        <Custom5 />
        <Custom6 />
        <Custom7 />
        <Custom8 />
        <Custom9 />
        <Custom10 />
        <Custom11 />
        <Custom12 />
        <Custom13 />
        <Custom14 />
        <Custom15 />
        <Custom16 />
        <Custom17 />
        <Custom18 />
        <Custom19 />
        <Custom20 />
        <AccountCode1>PARKING</AccountCode1>
        <AccountCode2 />
        <allocKey>ki7UU3hd447dlKuCVH6D7Sla83Di4kl</allocKey>
        <Percentage>100.00000000%</Percentage>
      </Allocations>
    </ExpenseEntry>
  </Entries>
</ReportDetails>

Locations v1.1

This API has been deprecated.

Partners and customers using a deprecated API should contact SAP Concur and discuss moving to the latest versions.

Learn more in the API Lifecycle & Deprecation Policy.

NOTE: Find the newer version 3.0 here

The valid city location codes in Concur. These location codes are used in the Post requests for the Expense Report service, when the City field is provided/required. The location codes vary by client, and cannot be used across multiple clients.

URI

https://www.concursolutions.com/api/expense/expensereport/v1.1/Locations

Get a list of locations

Retrieves a list of valid city location codes.

Request

Parameters

Parameter Required/Optional Description
city={_searchstring_} Required The city name. The system will return all values with city names that begin with the supplied name. The city name value is not case sensitive. The value can contain the * wildcard. This wildcard matches any number of characters. For example, Locations?city=old*b_o will match the city name "Old Saybrook"

Example

https://www.concursolutions.com/api/expense/expensereport/v1.1/Locations?city=Redmond

Headers

Response

Content types

application/xml

Payload

This request will return a LocationsList parent element with a Location parent element for each location with a City Name that contains the search text. The Location parent element contains the following child elements.

Location elements

Element Description
Name The city name.
Country The country name for the location.
State The state/province name for the location. Empty if there is no corresponding state/province.
LocationID The unique key for the location. This value is required when posting data in the City element.

Examples

XML example request

GET https://www.concursolutions.com/api/expense/expensereport/v1.1/Locations?city={_searchstring_} HTTP/1.1
Authorization: OAuth {access token}

XML example of successful response

HTTP/1.1 200 OK
Content-Type: application/xml
<LocationList xmlns="http://www.concursolutions.com/api/expense/expensereport/2011/03"    
  xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
  <Location>
    <Country>UNITED STATES</Country>
    <LocationID>nXipdPDzr4oCPylSOd91NQqQ$sqmnQrQxR</LocationID>
    <Name>Redmond</Name>
    <State>Washington</State>
  </Location>
  <Location>
    <Country>UNITED STATES</Country>
    <LocationID>8WWeksu7dEoHlsiIE$28kkj3ED8swhgGgye</LocationID>
    <Name>Redmond</Name>
    <State>Oregon</State>
  </Location>
  <Location>
    <Country>UNITED STATES</Country>
    <LocationID>Oe11hKEi$lslPncYAe2k2h7s67sdkkLEigUIF$</LocationID>
    <Name>Redmond</Name>
    <State>Utah</State>
  </Location>
</LocationList>

Reports v2

This API has been deprecated.

Partners and customers using a deprecated API should contact SAP Concur and discuss moving to the latest versions.

Learn more in the API Lifecycle & Deprecation Policy.

NOTE: Find the newer version 3.0 here.

The expense reports in Concur.

URI

https://www.concursolutions.com/api/expense/expensereport/v2.0/Report

GET List of Reports

The Get List of Reports version 2.0 endpoint can be used to get a list of reports for an entire company.

Request

Retrieves a list of up to 1000 reports to be used in financial and accounting system integration. This endpoint can be used to get a list of reports for the entire company.

Developers that are creating financial system integration may want to use the following search terms to get sets of reports ready for payment from Concur.

Developers can also use one or more of the following search terms to find reports.

Headers

Parameters

Parameter Description
BatchID The BatchID identifies which payment batch the reports are included in. The BatchID value is returned in the BatchID element in the Response of the Get Payment Batch List endpoint. This search term is used with Concur clients who have the Standard Expense and Concurforce products.
HasAttendees The HasAttendees query parameter returns reports that have one or more expense entries with attendees. The HasAttendees parameter supports the true value only.
Job Key The Jobkey identifies which accounting extract or payment batch the reports are included in. The Jobkey value is returned in the id element in the Response of the Post Extract Job Request endpoint, or the jobkey element in the Response of the Post Payment Batch Close endpoint. The View value, if provided, is ignored. This search term is used with Concur clients who have the Professional and Premium Expense products.
Status The Status value is designed to be used when retrieving reports for the entire company. It can be used only by OAuth consumers with the Web Services Admin role in Concur. If a request is sent by the Web Services Admin that does not contain a Status value, the Active status will be used. The possible status values are:
ReportCurrency The ReportCurrency identifies the reimbursement currency of the report. This value matches the reimbursement currency of the user who submitted the report. Format: 3-letter ISO 4217 currency code. Example: USD
PaymentTypeID The PaymentTypeID identifies the payment method for entries in the report. At least one entry in the report must have the specified payment type for the report to appear in the list. The possible payment types are returned in the PaymentTypeID element by the Get Expense Group Configuration function. The Payment Type Name of Cash signifies that the employee will be reimbursed directly for the expense.
ReimbursementMethod The ReimbursementMethod identifies the process that the report will be reimbursed with. When using the Reimbursement Method search term, it is recommended to also use the PaymentTypeID search term, where the Payment Type Name = Cash. While it's not required to use Payment Type Name = Cash, doing so delivers results that are relevant for employee reimbursement. The possible ReimbursementMethod values are listed below.
Report Country The Report Country search term returns all reports for the specified country. Format: The 2-letter ISO 3166-1 alpha-2 country code for report's country. Example: US
LoginID The LoginID is the Concur login for a report owner that is not the OAuth consumer. This limits the response to reports owned by the specified user.
ModifiedAfterDate This returns reports including their associated dependents (entries, itemizations, allocations, and attendees) that were modified after the specified date and time. This search term can be used along with other search terms to narrow the results. The date and time (if desired) should be in UTC. The format is: YYYY-MM-DDThh:mm:ss
ModifiedBeforeDate This returns reports including their associated dependents (entries, itemizations, allocations, and attendees) that were modified before the specified date and time. This search term can be used along with other search terms to narrow the results. The date and time (if desired) should be in UTC. The format is: YYYY-MM-DDThh:mm:ss

Status Enum

Value Description
ACTIVE Returns unsubmitted and unpaid (payment status is not Paid) reports.
UNSUBMITTED Returns unsubmitted reports.
PENDING Returns submitted reports pending approval.
ACCOUNTINGREVIEW Returns approved reports pending accounting review. These reports are waiting for the Processor to approve the report.
PROCESSING Returns processed reports pending financial integration. These reports have an Approval Status of Final Approval and a Payment Status of Unpaid.
INTEGRATED Returns reports with financial integration completed. These reports have a Payment Status of Paid.
PENDINGEXTERNALVALIDATION Returns reports that are at the Pending External Validation workflow step. This workflow step can be added after report submission and before the report is extracted for payment.
PAYMENTCONFIRMED Returns reports with confirmed payments. These reports have a Payment Status of Payment Confirmed.

Reimbursement MethodEnum

Value Description
ADPPAY ADP Payroll (via EPIP file)
APCHECK Company Check (via Accounts Payable)
CNQRPAY Expense Pay by Concur
PMTSERV Other reimbursement method

NOTE: The ReimbursementMethod search term is not available for Concur Premier- Professional and Premium clients.

XML Example Request by Status

GET https://www.concursolutions.com/api/expense/expensereport/v2.0/Reports/?status=PROCESSING  HTTP/1.1
Authorization: OAuth {access token}

XML Example Request by BatchID

GET https://www.concursolutions.com/api/expense/expensereport/v2.0/Reports/?batchid=5jj374sh$W2Lsa9y28w12  HTTP/1.1
Authorization: OAuth {access token}

XML Example Request for Reports with Attendees

GET https://www.concursolutions.com/api/expense/expenserepo/v2.0/Reports/?HasAttendees=true HTTP/1.1
Authorization: OAuth {access token}

XML Example Request by Job Key

GET https://www.concursolutions.com/api/expense/expensereport/v2.0/Reports/?jobkey=5jj374sh9y28w12  HTTP/1.1
Authorization: OAuth {access token}

XML Example Request by Report Currency

GET https://www.concursolutions.com/api/expense/expensereport/v2.0/Reports/?ReportCurrency=USD  HTTP/1.1
Authorization: OAuth {access token}

XML Example Request by Payment Type ID

GET https://www.concursolutions.com/api/expense/expensereport/v2.0/Reports/?PaymentTypeID=nr74tQrD8PorkF6yvS0Sm8ZeSGsw  HTTP/1.1
Authorization: OAuth {access token}

XML Example Request by Reimbursement Method and Payment Type

GET https://www.concursolutions.com/api/expense/expensereport/v2.0/Reports/?ReimbursementMethod=CNQRPAY&PaymentTypeID=nr74tQrD8PorkF6yvS0Sm8ZeSGsw  HTTP/1.1
Authorization: OAuth {access token}

XML Example Request by Report Country

GET https://www.concursolutions.com/api/expense/expensereport/v2.0/Reports/?reportcountry=US  HTTP/1.1
Authorization: OAuth {access token}

XML Example Request by Login ID

GET https://www.concursolutions.com/api/expense/expensereport/v2.0/Reports/?loginid=cm@example.com  HTTP/1.1
Authorization: OAuth {access token}

XML Example Request by Modified Date

GET https://www.concursolutions.com/api/expense/expenserepo/v2.0/Reports/?modifiedafterdate=2012-01-01T00:00:00 HTTP/1.1
Authorization: OAuth {access token}

Response

Headers

Payload

This request will return a ReportsList parent element with a ReportSummary child element for each report. The ReportSummary elements will have the following child elements:

Element Description
ReportName The name of the report. Maximum 40 characters.
ReportID The unique identifier for the report, which appears in the Concur Expense UI. Maximum 40 character varchar.
ReportCurrency The 3-letter ISO 4217 currency code for the expense report currency. Maximum 3 characters.
ReportTotal The total amount of the report. Maximum 23 characters.
ReportDate The create date of the report. Maximum 10 characters.
LastComment The text of the most recent comment on the report.
ReportDetailsURL The URL to access the report details.
ExpenseUserLoginID The Login ID of the user this report belongs to. Maximum 128 characters.
ApproverLoginID The Login ID of the user's expense approver. Maximum 128 characters.
EmployeeName The name of the expense report owner. Maximum 66 characters.
ApprovalStatus The report's approval status, in the OAuth consumer's language.
PaymentStatus The report's payment status, in the OAuth consumer's language.
ApprovalURL The URL the user can use to log in to Concur to approve the report. This element appears when requesting the TOAPPROVE view, and does not appear when using the Jobkey or BatchID search terms

NOTE: The ApprovalURL provides a link to Expense that can be used with SSO. The link can be put into a browser window, then the approver is automatically logged into Expense and the expense report opens if:

Otherwise, when the approver clicks the link, the Expense login page appears. The approver logs in and follows the normal steps for approving reports.

XML Example of Successful Response

HTTP/1.1 200 OK
Content-Type: application/xml
<ReportsList
  xmlns="http://www.concursolutions.com/api/expense/expensereport/2012/06">
  <ReportSummary>
    <ReportName>Client Meeting</ReportName>
    <ReportId>J20sh19D8lW2h8Dhs490ie</ReportId>
    <ReportTotal>175.23000000</ReportTotal>
    <ReportCurrency>USD</ReportCurrency>
    <ReportDate>2012-07-12T19:22:35</ReportDate>
    <LastComment>Dinner and drinks</LastComment>
    <Report-Full-Details-Url>https://www.concursolutions.com/api/expense/expensereport/v2.0/report/J20sh19D8lW2h8Dhs490ie</Report-Full-Details-Url>
    <ExpenseUserLoginID>cmiller@example.com</ExpenseUserLoginID>
    <ApproverLoginID>tbrown@example.com</ApproverLoginID>
    <EmployeeName>Chris Miller</EmployeeName>
    <ApprovalStatus>Final Approval</ApprovalStatus>
    <PaymentStatus>Unpaid</PaymentStatus>
  </ReportSummary>
  <ReportSummary>
    <ReportName>Trip to Seattle</ReportName>
    <ReportId>k1jDJ82H2h9as826h8hh2lk</ReportId>
    <ReportTotal>1212.72000000</ReportTotal>
    <ReportCurrency>USD</ReportCurrency>
    <ReportDate>2012-07-17T08:11:56</ReportDate>
    <LastComment></LastComment>
    <Report-Full-Details-Url>https://www.concursolutions.com/api/expense/expensereport/v2.0/report/k1jDJ82H2h9as826h8hh2lk</Report-Full-Details-Url>
    <ExpenseUserLoginID>tbrown@example.com</ExpenseUserLoginID>
    <ApproverLoginID>pdavis@example.com</ApproverLoginID>
    <EmployeeName>Terry Brown</EmployeeName>
    <ApprovalStatus>Final Approval</ApprovalStatus>
    <PaymentStatus>Unpaid</PaymentStatus>
  </ReportSummary>
</ReportsList>

Get Report Details Request

Retrieves the full set of information for the report. Includes the Report Header, Entry, Attendee, Itemization and Allocation details. NOTE: Some elements will appear only if the OAuth consumer has the Web Services Admin role. These include: The ReportKey element, the employee's credit card information, and the employee's bank account information, VAT information, Journal entries. Connectors that utilize this information go through a review process with Concur that includes verification of secure data handling.

Parameters

Parameter Description
{reportId} Required The identifier for the desired report. Example: https://www.concursolutions.com/api/expense/expensereport/v2.0/report/{reportId} URI Source: The ReportId is returned in the ReportId element of the Get List of Reports function.

Headers

XML Example Request

GET https://www.concursolutions.com/api/expense/expensereport/v2.0/report/n6ujbuLd1Arwe45lT7As3ThJYJf2dAsrrEW HTTP/1.1
Authorization: OAuth {access token}

Get Report Details Response

Headers

Payload

This request will return a ReportDetails parent element with the following child elements:

Element Description
UserLoginID The user ID of the report owner. Maximum 128 characters.
EmployeeName The name of the employee who created the report. Maximum 66 characters.
ReportID The unique identifier for the report, which appears in the Concur Expense UI. Maximum 32 character varchar.
ReportKey The unencrypted unique identifier for the report, that appears on the report header. The element appears only if the OAuth consumer has the Web Services Admin role in Concur. Maximum 48 characters.
ReportName The name of the report. Maximum 40 characters. Purpose The information from the Business Purpose field.
ReportDate The date from the report header. Format: YYYY-MM-DDThh:mm:ss
CreationDate The date the report was created. Format: YYYY-MM-DDThh:mm:ss
SubmitDate The date the report was submitted. Maximum 10 characters.
PaidDate The date the report was extracted for payment. This element has an attribute named i:nil. If the value for this element is null, the i:nil attribute will be set to true. Format: YYYY-MM-DDThh:mm:ss
CurrencyCode The 3-letter ISO 4217 currency code for the expense report currency. The expense report currency is defined as the report creator's default reimbursement currency.
ReportTotal The total amount of the report. Maximum 23 characters.
PersonalExpenses The total amount of expenses marked as personal. Maximum 23 characters.
AmountDueEmployee The total amount due to the employee for the report. Maximum 23 characters.
AmountDueCompanyCard The total amount due to the company card for the report. Maximum 23 characters.
TotalClaimedAmount The total amount of all non-personal expenses in the report. Maximum 23 characters.
TotalApprovedAmount The total amount of approved expenses in the report. Maximum 23 characters.
ApprovalStatusCode The approval status code for the report.
ApprovalStatusName The approval status name for the report.
PaymentStatusCode The unique identifier for the payment status of the report.
PaymentStatusName The payment status of the report.
OrgUnit1 through OrgUnit6 The details from the Org Unit custom fields. These may not have data, depending on configuration. Maximum 48 characters for each field.
Custom1 through Custom20 The details from the Custom fields. These may not have data, depending on configuration. If report owner information is stored in these fields, it may be outdated. Refer to the ReportOwner parent element for the current owner information. The custom fields may have the following child elements: Type (The custom field type. Will be one of the following: Amount, Boolean, ConnectedList, Date, Integer, List, Number, Text), Value (The value in the custom field. Maximum 48 characters.), Code (Custom list fields will include the list item code in this element.)
LedgerName The name of the expense report ledger. Maximum 20 characters.
PolicyID The unique identifier of the policy that applies to this report. Maximum 64 characters.
EverSentBack Whether the report has ever been sent back to the employee. Format: Y/N
HasException Whether the report has exceptions. Format: Y/N
WorkflowActionURL The URL to post a workflow action to the report using the Post Report Workflow Action function.
ExpenseEntriesList This parent element has an ExpenseEntry child element for each entry. Refer to the Expense Entry Child Elements table for more information.
ReportImageURL The URL to access the image associated with the report. This URL is valid for 30 minutes after the web service call.
Country The report country. Maximum 2 characters. Format: The ISO 3166-1 alpha-2 country code. Example: United States is US.
CountrySubdivision The report country subdivision. Format: ISO 3166-2:2007 country subdivision.
ProcessingPaymentDate The date that the report completed all approvals and was ready to be extracted for payment. Format: YYYY-MM-DD
ReceiptsReceived If Y, then this report has its receipt receipt confirmed by the Expense Processor. Format: Y/N
ReportOwner This parent element includes details about the employee who is the report owner. It saves the caller from calling the Get User Information function to get employee information commonly used in accounting integration. The ReportOwner element includes the most recent information about the report owner, at the time the report is requested. The ReportOwner parent element includes the following child elements: EmployeeCustom21 (The report owner's group ID. Maximum 48 characters.), EmployeeID (Employee ID often also serves as the employee's Vendor ID for AP system integrations or Payroll ID for Payroll integrations. Maximum 48 characters.), EmployeeOrgUnit1 through EmployeeOrgUnit6 (The report owner's organizational unit information. Maximum 48 characters for each field. FirstName (The report owner's first name. Maximum 32 characters.), LastName (The report owner's last name. Maximum 32 characters.), MiddleInitial (The report owner's middle initial. Maximum 1 character.), ReimbursementMethodCode (The report owner's reimbursement method code, as defined in the employee's Profile.)
EmployeeBankAccount This parent element includes the bank account data found on the Bank Information page in Profile. This data is used in Payment System integrations where the payment system reimburses the employee via this bank account. The EmployeeBankAccount parent element contains the following child elements: BankNumber (The bank identification number entered on the Bank Information page. Maximum 11 characters.), BankName (The bank name entered on the Bank Information page. Maximum 48 characters.), BranchLocation (The branch location entered on the Bank Information page. Maximum 30 characters.), AccountNumber (The bank account number entered on the Bank Information page. Maximum 100 characters.), AccountName (The name on the account entered on the Bank Information page.), PostalAddressLine1 (The postal address line 1 entered on the Bank Information page. Maximum 48 characters.), PostalAddressLine2 (The postal address line 2 entered on the Bank Information page. Maximum 48 characters.), PostalAddressCity (The postal address city entered on the Bank Information page. Maximum 24 characters.), PostalAddressRegion (The postal address region entered on the Bank Information page. Maximum 24 characters.), PostalAddressCode (The postal address code entered on the Bank Information page. Maximum 20 characters.), PostalAddressCountry (The postal address country entered on the Bank Information page. Maximum 2 characters. Format: The The ISO 3166-1 alpha-2 country code. Example: United States is US.)

Expense Entry Child Elements

Element Description
ReportEntryID The ID of the report entry. Maximum 13 characters.
ExpenseTypeID The expense type ID for the expense entry. Expense Type IDs are returned in the ExpKey element by the Get Expense Group Configuration endpoint.
ExpenseTypeName The expense type name. Maximum 64 characters.
SpendCategory The spend category specified for this expense type. Varies by client, used in reporting.
PaymentTypeCode The code for the payment type. Maximum 4 characters.
PaymentTypeName The name for the payment type. Maximum 80 characters.
TransactionDate The date of the expense entry. Maximum 10 characters. Format: YYYY-MM-DD
TransactionCurrencyName The name of the transaction currency. Example: US, Dollar
ExchangeRate The exchange rate that applies to the entry. Maximum 23 characters.
TransactionAmount The amount of the expense entry in the original transaction currency. Maximum 23 characters.
PostedAmount The amount of the expense entry in the user's reimbursement currency. The user's reimbursement currency is returned in the CrnCode element for the report. Maximum 23 characters.
ApprovedAmount The approved amount of the expense entry in the user's reimbursement currency.The user's reimbursement currency is returned in the CrnCode element for the report. Maximum 23 characters.
BusinessPurpose The text from the Business Purpose field of the entry. Maximum 64 characters.
VendorDescription The vendor name of the expense entry, which can be entered manually by the user or imported from the card transaction Merchant Name field. Maximum 64 characters.
LocationName The location for the expense entry, usually the city name.
LocationSubdivision The location's State, Province, or Country Subdivision. Maximum 6 characters.
LocationCountry The location's Country. Maximum 2 characters.
OrgUnit1 through OrgUnit The details from the Org Unit custom fields. These may not have data, depending on configuration. Maximum 48 characters for each field.
Custom1 through Custom40 The details from the Custom fields. These may not have data, depending on configuration. The custom fields may have the following child elements: Type (The custom field type. Will be one of the following: Amount, Boolean, ConnectedList, Date, Integer, List, Number, Text), Value (The value in the custom field. Maximum 48 characters.), Code (Custom list fields will include the list item code in this element.)
FormID The ID for the expense entry form.
EntryImageID The unique identifier for the image associated with the entry.
HasVat Whether the entry contains VAT data. Maximum 1 character. Format: Y/N
HasComments Whether the expense entry has comments. Maximum 1 character. Format: Y/N
CommentCount The number of comments associated with the expense entry.
IsItemized Whether the expense entry is itemized. Maximum 1 character. Format: Y/N
HasExceptions Whether the expense entry has exceptions. Maximum 1 character. Format: Y/N
IsPersonal Whether the expense entry is marked as personal. Maximum 1 character. Format: Y/N
HasAttendees Whether the expense entry has attendees. Maximum 1 character. Format: Y/N
HasAllocation Defines the amount of allocations for the expense. Maximum 1 character. Possible values are: P, for partial allocation, F, for full allocation, or N, for no allocation.
IsCreditCardCharge Whether the expense came from a credit card feed. Maximum 1 character. Format: Y/N
IsPersonalCardCharge Whether the expense came from a personal card feed. Maximum 1 character. Format: Y/N
ReceiptRequired Whether the original receipt is required for the entry. Maximum 1 character. Format: Y/N
ImageRequired Whether a receipt image is required for the entry. Maximum 1 character. Format: Y/N
E-ReceiptID The ID for the attached e-receipt, if available.
LastModifiedDate The date the expense entry was last changed. Maximum 19 characters. Format: YYYY-MM-DDThh:mm:ss
ItemizationsList The list of itemizations for the expense entry. This parent element will have at least one Itemization child element. If the expense entry is not itemized, the Itemization will contain the same values as the entry. If the expense entry has itemizations, there will be one Itemization child element for each itemization. Refer to the Itemization Entry Details Child Elements table for more information. NOTE: There are a few rare cases where the ItemizationsList will be null. This happens when a report entry has a payment type code that is not IBCP with offsets or CBCP and there is a Regular or Child expense entry with an Approved Amount equal to zero. The expense entry will have a Null ItemizationsList.
ReportEntryVendorName Vendor name the employee selected from the Vendor list field. Maximum 64 characters.
ReportEntryReceiptReceived If Y, then this entry has been marked as reviewed by a processor. Maximum 1 character. Format: Y/N
ReportEntryReceiptType Maximum 1 character. One of these: T = tax receipt, R = regular receipt, N = no receipt
CardTransaction This parent element includes the card transaction data found in the card transaction associated to this expense entry. This data is used in Payment System integrations where the payment system reimburses the card issuer for the indicated card account. Refer to the Card Transaction Child Elements field.
ExpensePay Whether the entry was paid using the Expense Pay service. This element have a value if the report has reached the Processing Payment workflow step. Format: Yes/No

Itemization Entry Details Child Elements

Element Description
ItemType The type of itemization. If the expense entry does not have any itemizations, this will be set to Regular. If the expense entry contains itemizations, each one will be set to Child.
ItemizationID The unique identifier for the itemization. Maximum 19 characters.
ExpenseTypeID The expense type ID for the itemization.
ExpenseTypeName The expense type for the itemization. Maximum 64 characters.
TransactionDate The date of the transaction. Maximum 10 characters. Format: YYYY-MM-DD
TransactionAmount The amount for the itemization in the expense currency. Maximum 23 characters.
PostedAmount The amount for the itemization in the user's reimbursement currency. The user's reimbursement currency is returned in the CrnCode element for the report. Maximum 23 characters.
ApprovedAmount The approved amount of the itemization in the user's reimbursement currency. The user's reimbursement currency is returned in the CrnCode element for the report. Maximum 23 characters.
BusinessPurpose The business purpose field from the report header.
OrgUnit1 through OrgUnit6 The details from the Org Unit custom fields. These may not have data, depending on configuration. Maximum 48 characters for each field.
Custom1 through Custom40 The custom fields associated with the itemization. These may not have data, depending on your configuration. The custom fields may have the following child elements: Type (The custom field type. Will be one of the following: Amount, Boolean, ConnectedList, Date, Integer, List, Number, Text), Value (The value in the custom field. Maximum 48 characters.), Code (Custom list fields will include the list item code in this element.)
HasComments Whether the itemization has comments. Maximum 1 character. Format: Y/N
CommentCount The number of comments associated with the itemization.
IsPersonal Whether the itemization is personal. Maximum 1 character. Format: Y/N
LastModified The UTC date when the itemization was last modified. Maximum 19 characters. Format: YYYY-MM-DDThh:mm:ss
AttendeesList This parent element contains one Attendee element for each associated attendee. The Attendee element contains child elements
AllocationsList This parent element contains at least one Allocation element. It will contain multiple Allocation elements if there are multiple allocations for the itemization.

Attendee List Child Elements

Element Description
AttendeeType The type of attendee. Maximum 40 characters.
FirstName The attendee's first name. Maximum 50 characters.
LastName The attendee's last name. Maximum 132 characters.
Company The attendee's company name. Maximum 150 characters.
Title The attendee's title. Maximum 32 characters.
ExternalID The unique identifier for the attendee, managed outside Concur. Maximum 48 characters.
Custom1 through Custom20 The details from the Custom fields. These may not have data, depending on configuration. The custom fields may have the following child elements: Type (The custom field type. Will be one of the following: Amount, Boolean, ConnectedList, Date, Integer, List, Number, Text), Value (The value in the custom field. Maximum 100 characters.), Code (Custom list fields will include the list item code in this element.)
HasExceptionsPrevYear Whether the attendee has exceptions in the previous year, based on yearly total limits for attendees. Maximum 1 character. Format: Y/N
HasExceptionsYTD Whether the attendee has exceptions in the current year, based on yearly total limits for attendees. Maximum 1 character. Format: Y/N
IsDeleted Whether the attendee is marked as deleted. Maximum 1 character. Format: Y/N
OwnerName The name of the employee that owns the attendee record.
TotalAmountPrevYear The total amount spent on the attendee in the previous calendar year.
TotalAmountYTD The total amount spent on the attendee in the current calendar year.
VersionNumber The attendee's version number.
AttendeeID Attendee unique identifier within Concur.
AttendeeTypeCode The unique identifier for the attendee type.
AttendeeOwnerID The unique identifier for the person or system that owns the attendee.
CurrencyCode The 3-letter ISO 4217 currency code for attendee related amounts.

Allocations List Child Elements

Element Description
AllocationID The unique alphanumeric identifier for the allocation. Maximum 13 characters.
Percentage The percentage of the expense that is included in this allocation. Maximum 11 characters.
AccountCode1 The primary accounting code assigned to the expense type associated with this allocation. Typically, expense types have only this primary account code.
AccountCode2 The secondary or alternative accounting code assigned to the expense type associated with this allocation. In rare cases some expense types include this accounting code to handle special cases. One example of these special cases is when using travel allowance, where one expense would use the primary account code for the allowed amount, and the alternative account code for the overage. Another example is personal use of a company car. Refer to the Expense: Account Codes Setup Guide for more information on how Concur Expense determines which accounting codes to use.
Custom1 through Custom20 The custom fields associated with the allocation. These may not have data, depending on your configuration. The custom fields may have the following child elements: Type (The custom field type. Will be one of the following: Amount, Boolean, ConnectedList, Date, Integer, List, Number, Text), Value (The value in the custom field. Maximum 48 characters.), Code (Custom list fields will include the list item code in this element.)
JournalEntriesList This parent element contains at least one JournalEntry child element. It contains multiple JournalEntry elements if the allocation has multiple journal entries. The JournalEntry element contains child elements
VATDataList This parent element contains one VATData element for each VAT line item. This element will be empty if there are no VAT line items. The VATData parent element contains child elements

JournalEntry Child Elements

Element Description
JournalID Unique identifier for the journal entry.
PayerPaymentTypeName Payer payment type. Maximum 64 characters. One of these: Company = Company, Employee = Employee, Payment Type for the Credit Card Payment Type
PayerPaymentTypeCode Payment code name for the payer. Maximum 80 characters.
PayeePaymentTypeName Payee payment type. Maximum 64 characters. One of these: Company = Company, Employee = Employee Payment Type for the Credit Card Payment Type
PayeePaymentCode Payment code name for the payee. Maximum 80 characters.
AccountCode The account code Concur Expense determines should apply to this journal entry. For journal entries associated to an allocation, Concur Expense uses the business logic described in the Expense: Account Codes Setup Guide to determine whether the primary or secondary account code should apply. When there is no allocation associated to the journal entry, Concur Expense uses clearing account codes for Credit Card and Cash Advance for personal use of a company paid expense or a cash advance issued to an employee respectively. Maximum 48 characters. NOTE: The developer should almost always use this accounting code when creating financial transactions in financial systems. In some situations a developer may need to use the accounting codes in the Allocation parent element.
DebitOrCredit Maximum 2 characters. Either: DR = Debit, CR = credit
Amount Value, as credit or debit, of the amount to be exchanged between the payer and payee for this expense account code (not an absolute value) Maximum 23 characters. EXAMPLES: Value of zero, credit, or debit, as the following: 0 (Zero) "0", + (Plus / Debit) "+50.00", - (Minus / Credit) "-50.00"
JobRunKey Either the unique identifier for job run for the accounting extract that processed this journal, or a static value indicating the journal was processed by Manual Pay, Expense Pay, or some other system.

VATData Child Elements

Element Description
TaxName Tax authority name. Maximum 50 characters.
TaxAuthorityLabel 5-digit code that appears on the expense entry pages. Maximum 5 characters.
TaxTransactionAmount Calculated tax amount for this expense in the spend currency. Maximum 23 characters.
TaxPostedAmount Calculated tax amount for this expense entry in the reimbursement currency. Maximum 23 characters.
Source Specifies how the tax data was derived. Maximum 4 characters. One of these: CARD= Provided from company card, USER = Entered by employee, SYST = Calculated by system, PROC = Entered by processor
TaxReclaimTransactionAmount Calculated amount of tax eligible for reclaim in the spend currency. Maximum 23 characters.
TaxReclaimPostedAmount Calculated amount of tax eligible for reclaim in the reimbursement currency. Maximum 23 characters.

Card Transaction Child Elements

Element Description
AccountNumber Credit card number (not encrypted) used for this expense. Maximum 255 characters.
CardDescription The name on the credit card used for this expense. Maximum 255 characters.
CardTypeCode Type of credit card.
TransactionReferenceNumber Reference number from the credit card vendor. Maximum 64 characters.
TransactionCCTType Transaction type supplied by card vendor. Maximum 3 characters. One of these: ANF = Annual Fees, CAV = Cash Advance, CCF = Cash and Check Fees, CHG = Other Bank Charges and Fees, FNC = Finance Charges, LAF = Late Fees, NSF = Insufficient Funds Check Fees, PAY = Payment, RPE = Credit Card Transaction
TransactionID Calculated value assigned to this card entry during the import process. Maximum 32 characters.
TransactionAmount Amount of the charge in the spend currency. Maximum 23 characters.
TaxAmount Amount of tax on the transaction amount (if provided by card vendor). Maximum 23 characters.
TransactionAlphaCode Currency code for the spend currency. Maximum 3 characters. Format: ISO 4217 3 digit alpha code
PostedAmount Amount of the charge in the billing currency of the card. Maximum 23 characters.
PostedAlphaCode Currency code for the card billing currency. Maximum 3 characters. Format: ISO 4217 3 digit alpha code
TransactionDate Date the charge was made at the merchant. Maximum 10 characters.
PostedDate Date the charge was posted to the credit card account. Maximum 10 characters.
Description Description of the charge from the merchant. Maximum 42 characters.
MasterCardCode Merchant code sent from the credit card vendor. Maximum 5 characters.
TransactionMerchantName Name of the merchant. Maximum 50 characters.
MerchantCity Merchant city. Maximum 40 characters.
MerchantState Merchant State/Province. Maximum 32 characters.
MerchantCountryCode Merchant country location code. Format: 2 digit alpha code
MerchantReferenceNumber Merchant reference number passed from the merchant to the card. Maximum 15 characters.
ExchangeRateFromBillingToEmployeeCurrency Currency exchange rate used between the credit card billing currency and the employee's reimbursement currency. Maximum 23 characters.
BillingAmount Amount due to the company card from the employee or company (depending on who is responsible for the bill) for this detail row. Maximum 23 characters.

XML Example of Successful Response

HTTP/1.1 200 OK
Content-Type: application/xml
<?xml version="1.0" encoding="utf-8"?>
<ReportDetails xmlns="http://www.concursolutions.com/api/expense/expensereport/2012/07" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
  <UserLoginID>cm@example.com</UserLoginID>
  <EmployeeName>Miller, Chris</EmployeeName>
  <ReportID>425FE2ADB4954FCA90CD</ReportID>
  <ReportName>Client Meeting</ReportName>
  <Purpose>Sales meeting</Purpose>
  <ReportDate>2013-01-10T00:00:00</ReportDate>
  <CreationDate>2013-01-11T01:58:20</CreationDate>
  <SubmitDate>0001-01-01T00:00:00</SubmitDate>
  <PaidDate i:nil="true" />
  <CurrencyCode>USD</CurrencyCode>
  <ReportTotal>50.00000000</ReportTotal>
  <PersonalExpenses>0.00000000</PersonalExpenses>
  <AmountDueEmployee>50.00000000</AmountDueEmployee>
  <AmountDueCompanyCard>0.00000000</AmountDueCompanyCard>
  <TotalClaimedAmount>50.00000000</TotalClaimedAmount>
  <TotalApprovedAmount>50.00000000</TotalApprovedAmount>
  <ApprovalStatusCode>A_NOTF</ApprovalStatusCode>
  <ApprovalStatusName>Not Submitted</ApprovalStatusName>
  <PaymentStatusCode>P_NOTP</PaymentStatusCode>
  <PaymentStatusName>Not Paid</PaymentStatusName>
  <OrgUnit1>Sales</OrgUnit1>
  <OrgUnit2 />
  <OrgUnit3 />
  <OrgUnit4 />
  <OrgUnit5 />
  <OrgUnit6 />
  <Custom1 />
  <Custom2 />
  <Custom3 />
  <Custom4 />
  <Custom5 />
  <Custom6 />
  <Custom7 />
  <Custom8 />
  <Custom9 />
  <Custom10 />
  <Custom11 />
  <Custom12 />
  <Custom13 />
  <Custom14 />
  <Custom15 />
  <Custom16 />
  <Custom17 />
  <Custom18 />
  <Custom19 />
  <Custom20 />
  <LedgerName>Corporate</LedgerName>
  <PolicyID>ndrF8hjzl9FtFUdfaBwVvXP$sD1vDpRKNf</PolicyID>
  <EverSentBack>N</EverSentBack>
  <HasException>N</HasException>
  <WorkflowActionURL />
  <ExpenseEntriesList>
    <ExpenseEntry>
      <ReportEntryID>nE0avYnILN9mHdTErNSd2pH45udFoNQ$po</ReportEntryID>
      <ExpenseTypeID>BUSML</ExpenseTypeID>
      <ExpenseTypeName>Business Meal (attendees)</ExpenseTypeName>
      <SpendCategory>Entertainment</SpendCategory>
      <PaymentTypeCode>CASH</PaymentTypeCode>
      <PaymentTypeName>Cash</PaymentTypeName>
      <TransactionDate>2013-01-10T00:00:00</TransactionDate>
      <TransactionCurrencyName>US, Dollar</TransactionCurrencyName>
      <ExchangeRate>1.00000000000000</ExchangeRate>
      <TransactionAmount>50.00000000</TransactionAmount>
      <PostedAmount>50.00000000</PostedAmount>
      <ApprovedAmount />
      <BusinessPurpose />
      <VendorDescription />
      <LocationName>Washington</LocationName>
      <LocationSubdivision>US-DC</LocationSubdivision>
      <LocationCountry>US</LocationCountry>
      <OrgUnit1>Sales</OrgUnit1>
      <OrgUnit2 />
      <OrgUnit3 />
      <OrgUnit4 />
      <OrgUnit5 />
      <OrgUnit6 />
      <Custom1 />
      <Custom2 />
      <Custom3 />
      <Custom4 />
      <Custom5 />
      <Custom6 />
      <Custom7 />
      <Custom8 />
      <Custom9 />
      <Custom10 />
      <Custom11 />
      <Custom12 />
      <Custom13 />
      <Custom14 />
      <Custom15 />
      <Custom16 />
      <Custom17 />
      <Custom18 />
      <Custom19 />
      <Custom20 />
      <Custom21 />
      <Custom22 />
      <Custom23 />
      <Custom24 />
      <Custom25 />
      <Custom26 />
      <Custom27 />
      <Custom28 />
      <Custom29 />
      <Custom30 />
      <Custom31 />
      <Custom32 />
      <Custom33 />
      <Custom34 />
      <Custom35 />
      <Custom36 />
      <Custom37 />
      <Custom38 />
      <Custom39 />
      <Custom40 />
      <FormID>nAaT8$puKKOhs7h2wespCW7vyyxJAJcyb5</FormID>
      <EntryImageID />
      <HasVat>N</HasVat>
      <HasComments>N</HasComments>
      <CommentCount>0</CommentCount>
      <IsItemized>Y</IsItemized>
      <HasExceptions>N</HasExceptions>
      <IsPersonal>N</IsPersonal>
      <HasAttendees>Y</HasAttendees>
      <HasAllocation>N</HasAllocation>
      <IsCreditCardCharge>N</IsCreditCardCharge>
      <IsPersonalCardCharge>N</IsPersonalCardCharge>
      <ReceiptRequired>N</ReceiptRequired>
      <ImageRequired>N</ImageRequired>
      <E-ReceiptID />
      <LastModified>2013-01-11T01:59:52</LastModified>
      <ItemizationsList>
        <Itemization>
          <ItemType>Regular</ItemType>
          <ItemizationID>nE0avYnILN9mHdTErNSd2pH45udFoNQ$po</ItemizationID>
          <ExpenseTypeID>BUSML</ExpenseTypeID>
          <ExpenseTypeName>Business Meal (attendees)</ExpenseTypeName>
          <TransactionDate>2013-01-10T00:00:00</TransactionDate>
          <TransactionAmount>50.00000000</TransactionAmount>
          <PostedAmount>50.00000000</PostedAmount>
          <ApprovedAmount />
          <BusinessPurpose />
          <OrgUnit1>Sales</OrgUnit1>
          <OrgUnit2 />
          <OrgUnit3 />
          <OrgUnit4 />
          <OrgUnit5 />
          <OrgUnit6 />
          <Custom1 />
          <Custom2 />
          <Custom3 />
          <Custom4 />
          <Custom5 />
          <Custom6 />
          <Custom7 />
          <Custom8 />
          <Custom9 />
          <Custom10 />
          <Custom11 />
          <Custom12 />
          <Custom13 />
          <Custom14 />
          <Custom15 />
          <Custom16 />
          <Custom17 />
          <Custom18 />
          <Custom19 />
          <Custom20 />
          <Custom21 />
          <Custom22 />
          <Custom23 />
          <Custom24 />
          <Custom25 />
          <Custom26 />
          <Custom27 />
          <Custom28 />
          <Custom29 />
          <Custom30 />
          <Custom31 />
          <Custom32 />
          <Custom33 />
          <Custom34 />
          <Custom35 />
          <Custom36 />
          <Custom37 />
          <Custom38 />
          <Custom39 />
          <Custom40 />
          <HasComments>N</HasComments>
          <CommentCount>0</CommentCount>
          <IsPersonal>N</IsPersonal>
          <LastModified>2013-01-11T01:59:52</LastModified>
          <AllocationsList />
          <AttendeesList>
            <Attendee>
              <AttendeeType>BUSGUEST</AttendeeType>
              <FirstName>Pat</FirstName>
              <LastName>Davis</LastName>
              <Company />
              <Title />
              <ExternalID />
              <Custom1 />
              <Custom2 />
              <Custom3 />
              <Custom4 />
              <Custom5 />
              <Custom6 />
              <Custom7 />
              <Custom8 />
              <Custom9 />
              <Custom10 />
              <Custom11 />
              <Custom12 />
              <Custom13 />
              <Custom14 />
              <Custom15 />
              <Custom16 />
              <Custom17 />
              <Custom18 />
              <Custom19 />
              <Custom20 />
              <HasExceptionsPrevYear>N</HasExceptionsPrevYear>
              <HasExceptionsYTD>N</HasExceptionsYTD>
              <IsDeleted>N</IsDeleted>
              <OwnerEmpName>Miller, Chris</OwnerEmpName>
              <TotalAmountPrevYear>0.00000000</TotalAmountPrevYear>
              <TotalAmountYTD>0.00000000</TotalAmountYTD>
              <VersionNumber>1</VersionNumber>
              <AttendeeID>nFaAj038Hw$plfUD8be0I45wTx8$sMlTd$pP</AttendeeID>
              <AttendeeTypeCode>BUSGUEST</AttendeeTypeCode>
              <AttendeeOwnerID>cm@example.com</AttendeeOwnerID>
              <CurrencyCode>USD</CurrencyCode>
            </Attendee>
          </AttendeesList>
        </Itemization>
        <Itemization>
          <ItemType>Child</ItemType>
          <ItemizationID>nE0avYnILN9g$s6lCFX0jFBWmHAiTYYf9C</ItemizationID>
          <ExpenseTypeID>BRKFT</ExpenseTypeID>
          <ExpenseTypeName>Breakfast</ExpenseTypeName>
          <TransactionDate>2013-01-10T00:00:00</TransactionDate>
          <TransactionAmount>50.00000000</TransactionAmount>
          <PostedAmount>50.00000000</PostedAmount>
          <ApprovedAmount>50.00000000</ApprovedAmount>
          <BusinessPurpose />
          <OrgUnit1>Sales</OrgUnit1>
          <OrgUnit2 />
          <OrgUnit3 />
          <OrgUnit4 />
          <OrgUnit5 />
          <OrgUnit6 />
          <Custom1 />
          <Custom2 />
          <Custom3 />
          <Custom4 />
          <Custom5 />
          <Custom6 />
          <Custom7 />
          <Custom8 />
          <Custom9 />
          <Custom10 />
          <Custom11 />
          <Custom12 />
          <Custom13 />
          <Custom14 />
          <Custom15 />
          <Custom16 />
          <Custom17 />
          <Custom18 />
          <Custom19 />
          <Custom20 />
          <Custom21 />
          <Custom22 />
          <Custom23 />
          <Custom24 />
          <Custom25 />
          <Custom26 />
          <Custom27 />
          <Custom28 />
          <Custom29 />
          <Custom30 />
          <Custom31 />
          <Custom32 />
          <Custom33 />
          <Custom34 />
          <Custom35 />
          <Custom36 />
          <Custom37 />
          <Custom38 />
          <Custom39 />
          <Custom40 />
          <HasComments>N</HasComments>
          <CommentCount>0</CommentCount>
          <IsPersonal>N</IsPersonal>
          <LastModified>2013-01-11T01:59:52</LastModified>
          <AllocationsList>
            <Allocation>
              <AllocationID>ngYn5SB4OUXgRV6P8VgsQQr88SaKYvbqz</AllocationID>
              <Percentage>100.00000000%</Percentage>
              <AccountCode1>AC_BRKFT1</AccountCode1>
              <AccountCode2>AC_BRKFT2</AccountCode2>
              <Custom1 />
              <Custom2 />
              <Custom3 />
              <Custom4 />
              <Custom5 />
              <Custom6 />
              <Custom7 />
              <Custom8 />
              <Custom9 />
              <Custom10 />
              <Custom11 />
              <Custom12 />
              <Custom13 />
              <Custom14 />
              <Custom15 />
              <Custom16 />
              <Custom17 />
              <Custom18 />
              <Custom19 />
              <Custom20 />
              <VATDataList />
            </Allocation>
          </AllocationsList>
          <AttendeesList />
        </Itemization>
      </ItemizationsList>
      <UserLoginID>cm@example.com</UserLoginID>
    </ExpenseEntry>
  </ExpenseEntriesList>
  <Country>US</Country>
  <CountrySubdivision></CountrySubdivision>
  <ProcessingPaymentDate></ProcessingPaymentDate>
  <ReceiptsReceived>Y</ReceiptsReceived>
  <ReportOwner>
    <EmployeeID>cm@example.com</EmployeeID>
    <LastName>Chris</LastName>
    <FirstName>Miller</FirstName>
    <MiddleInitial></MiddleInitial>
    <EmployeeCustom21></EmployeeCustom21>
    <EmployeeOrgUnit1></EmployeeOrgUnit1>
    <EmployeeOrgUnit2></EmployeeOrgUnit2>
    <EmployeeOrgUnit3></EmployeeOrgUnit3>
    <EmployeeOrgUnit4></EmployeeOrgUnit4>
    <EmployeeOrgUnit5></EmployeeOrgUnit5>
    <EmployeeOrgUnit6></EmployeeOrgUnit6>
    <ReimbursementMethodCode>CNQRPAY</ReimbursementMethodCode>
  </ReportOwner>
</ReportDetails>

Direct Connect - Hotel v1

This API has been deprecated.

Partners and customers using a deprecated API should contact SAP Concur and discuss moving to the latest versions.

Description

The Hotel Services Direct Connect provides a method for Travel users to access hotel inventory.

Once the hotel supplier has developed and certified their interface with SAP Concur, their inventory will begin appearing in hotel searches by opted-in Travel users.

This callout differs from the inbound SAP Concur web services in the following ways:

Works With These SAP Concur Products

Product Restrictions

This direct connect is only available to Travel Suppliers with Hotel inventory. This direct connect is not supported in the SAP Concur mobile application.

SAP Concur products are highly configurable, and not all clients will have access to all features.

Partner developers must determine which configurations are required for their solution prior to the application review process.

Hotel Process Overview

The configuration process has the following steps:

  1. The Hotel Supplier creates the application on their system that will accept the requests from SAP Concur and return the appropriate responses.
  2. The Hotel Supplier creates the endpoint on their system that SAP Concur uses to access their inventory.
  3. SAP Concur creates a production company for the Hotel Supplier.
  4. The Hotel Supplier registers their application with SAP Concur by logging in to their production company.
  5. SAP Concur and the Hotel Supplier validate the application:
    • The Hotel Supplier develops to the SAP Concur API and provides a test system.
    • The Hotel Supplier provides the URIs and credentials for their test system to SAP Concur.
    • SAP Concur sets up the vendor in the certification systems and runs a series of tests to validate the interaction between the two systems.
    • Once certification passes, the Hotel supplier sends SAP Concur the production URIs and credentials.
    • SAP Concur updates the production servers with the supplier's production data and does a test booking. Upon successful completion, the supplier will be live in SAP Concur for any customer to enable.
  6. The Travel client opts in to the Hotel callout (within the Travel Configuration) to allow their users to view and book the available inventory.

Once the configuration is complete, the callout uses the following process:

  1. The user searches for hotels when creating an itinerary in Travel.
  2. Travel sends the search request to the endpoint, using the Post HotelSearch.
  3. The supplier returns the properties.
  4. Travel sends a request for rates for some of the properties using the Post HotelAvail request. The number of properties is configurable with a current maximum of 25. More than one property may be specified in each Post HotelAvail request.
  5. If the user chooses to reserve a hotel room, Travel sends the Post HotelBookingRule and shows the booking and cancellation policies to the user.
  6. If the user accepts the policy, Travel sends the Post HotelRes.
  7. Travel will send Post HotelItin requests to show the user their reservation. This will happen whenever the user views their itinerary.

This callout can also be used to perform the following functions:

Hotel URL Structure

The hotel direct connect sends the relevant information to a URL that the travel supplier maintains.

A recommended URL structure is: https://{servername}/concur/hotel/v1/

The URL is provided by the supplier when registering the partner application.

You can use either one endpoint for all messages, or a dedicated one for each message type. In that case you have to follow these rules:

The only allowed difference between the endpoint URLs can be the message name (without OTA_ and RQ/RS):

https://{servername}/concur/hotel/v1/HotelSearch
https://{servername}/concur/hotel/v1/HotelAvail

The variable part doesn't need to be at the end:

https://{servername}/concur/hotel/HotelSearch/v1/
https://{servername}/concur/hotel/HotelAvail/v1/

Security

SAP Concur will make calls to the application connector's endpoint using SSL. During configuration, SAP Concur will connect to the application connector to validate that its hostname and access credentials are valid.

SAP Concur will not be able to connect to the application connector until a certificate signed by a Certificate Authority (CA) is installed in the application connector. If you are hosting the application connector, you will need to install the signed certificate before SAP Concur can access the connector.

SAP Concur will use Http Basic authentication. The hotel supplier will need to provide credentials that SAP Concur will send to the supplier's system for each message.

Outbound Messages

The SAP Concur outbound message format is based upon a subset of the OTA2011B hotel standard. Please refer to the Function links below for the details of the request and response format.

Please note the following general information about this format:

Functions

Additional Information

Concur Travel Configuration

The Travel clients opt in to the Hotel inventory using a setting in the Travel Configuration. Clients must contact SAP Concur to have this setting activated.

Versioning

In most cases, new versions of Hotel Services will involve adding support for various optional nodes and attributes in the OTA standards. These changes will be backwards compatible and should not require any mandatory changes and hotel suppliers will be upgrade automatically. In the situation where a change is implemented which cannot be made backwards compatible, suppliers will need to upgrade the Hotel Services interface by and provide a new set of hotel URIs. SAP Concur recommends that the version of the interface be part of the hotel URI provided by the hotel suppliers.

Certification

The certification process will start once the vendor has completed their integration with the SAP Concur certification systems. Certification consists of running through several use cases on the certification servers and validating that in each scenario the correct response is sent. Typically, most potential issues are being worked out during the integration process and certification can be accomplished in a day or two. An example of a use case during certification would be a user searching and booking a property several months out, viewing an itinerary, changing the dates of the property, and then cancelling the reservation.

Responses and Errors

For error handling we don't use any special message. Just return the appropriate response, only replace Success node with Errors and provide some error description. Please follow the OTA Code Table for error codes. Please provide as descriptive error text as possible. It will make tracing problems lot easier on both sides.

General Requirements

Information on format or value requirements that are used in multiple endpoints is included here.

Codes

All the codes used by the Hotel Direct Connect are documented in the Hotel Direct Connect Codes.

Corporate Identifier

The corporate identifier will be passed as RequestorID node. The values will be configured on setup. Please keep the Type compliant with ID Type Codes.

<POS>
  <Source ISOCountry="US" ISOCurrency="USD">
    <RequestorID Type="4" ID="7777777" ID_Context="MyHotel" />
  </Source>
</POS>

If a vendor requires additional identification of the client system (all calls to vendor will have the same value), you can provide a second RequestorID:

<POS>
  <Source ISOCountry="US" ISOCurrency="USD">
    <RequestorID Type="4" ID="7777777" ID_Context="MyHotel" />
    <RequestorID Type="7" ID="8172927" ID_Context="WholeTravel" />
  </Source>
</POS>

Please keep the Type compliant with ID Type Codes. The supported codes for the Requestor ID Type are: 1,2,3,4,5,7,9,13,18,21

ID Type Codes Table

Code Description
1 Customer
2 CRO (Customer Reservations Office)
3 Corporation representative
4 Company
5 Travel agency
6 Airline
7 Wholesaler
8 Car rental
9 Group
10 Hotel
11 Tour operator
12 Cruise line
13 Internet broker
14 Reservation
15 Cancellation
18 Other
21 Profile
25 Associated reservation
26 Associated itinerary reservation
27 Associated shared reservation
32 Merchant
33 Acquirer
34 Master reference
35 Purged master reference
36 Parent reference
37 Child reference
38 Linked reference
39 Contract
40 Confirmation number

Hotel v1 - Codes

This API has been deprecated.

Partners and customers using a deprecated API should contact SAP Concur and discuss moving to the latest versions.

Learn more in the API Lifecycle & Deprecation Policy.

Hotel Direct Connect Codes

OTA Error Codes

Code Description
15 Invalid date
61 Invalid currency code
69 Minimum stay criteria not fulfilled
181 Invalid country code
243 Invalid ARC/IATA number
245 Invalid confirmation number
290 Invalid state/province/territory code
291 Invalid zip/postal code
322 No availability
323 All not valid
342 Cancel fee may apply
343 Can't sell, file maintenance is active
344 Can't sell, record maintenance is active
345 Can't sell, inventory reconcile is active
346 Closed to arrivals
347 Company address required
348 Company or travel agent address required
349 Contact housing office
350 Credit card deposits only
351 Credit card guarantee not accepted at hotel
352 Invalid credit card type
353 Departure date is past dated
354 Deposit forfeiture and/or refund may apply
355 Deposit/guarantee due immediately
356 Invalid action/status code
357 Invalid city
358 Error convention/group code
359 Error convention/group name
360 Error entry code
361 Invalid hotel
362 Invalid number of nights
363 Invalid number of rooms
364 Error rate range
365 Error credit card
366 Error during processing, please retry
367 Invalid format
368 Error no active accommodation
369 Frequency (SMTWTFS) specified does not match date
370 Frequent guest points cannot be redeemed at this time
371 Full payment or deposit required
372 Guarantee code not accepted at this hotel
373 Guarantee required immediately
374 Guaranteed room type is not offered by this brand
375 Hotel not active
376 Hotel full check alternated
377 Invalid - max number of nights exceeded
378 Invalid - max number of rooms exceeded
379 Invalid - only one name allowed
380 Invalid arrival date for group
381 Invalid check-in date
382 Invalid check-out date
383 Invalid city code
384 Invalid client file for product type
385 Invalid confirmation or cancellation number
386 Invalid fax number
387 Invalid guarantee option
388 Invalid guaranteed room type
389 Invalid guarantee type
390 Invalid hold type
391 Invalid hold until time
392 Invalid hotel code
393 Invalid hotel location type
394 Invalid item
395 Invalid message text
396 Invalid name
397 Invalid number of adults
398 Invalid number specified
399 Invalid product type code
400 Invalid property code
401 Invalid rate requested field
402 Invalid room type
403 Invalid segment type
404 Invalid start/end date combination
405 Invalid vendor
406 Invalid for convention/group
407 Item too long
408 Last page of data already displayed
409 Maximum length of stay restriction
410 Minimum length of stay error
411 Minimum length of stay restriction
412 Modification completed
413 Modify
414 More days were specified than exist in inventory
415 Multiple hotels in same GNR not allowed
416 Multi-room/name combination invalid
417 Name change not allowed
418 Name/address missing
419 Need names
420 Need e-mail address
421 No rooms available for waitlist
422 No active accommodation found
423 No alternates defined for requested location
424 No hotels found which match this input
425 No match found
426 No rates offered for this sell request
427 No rooms available for requested dates
428 No tax information available
429 Number nights deposit exceeds stay
430 Ok
431 Out date past end date
432 Payment or deposit required, no non-guaranteed holds
433 Please book on a separate reservation
434 Product requested not in city requested
435 Property name required
436 Rate does not exist
437 Rate unavailable
438 Requested rate not available
439 Reenter
440 Request completed
441 Requested rate not available for entire stay
442 Requested rate not available for waitlist
443 Requested rate not offered at this location
444 Restrictions - limit 1 room
445 Seasonal rate change error
446 Service request not allowed
447 Unable to update - simultaneous updates
448 System error
449 Unable to add IATA nbr to existing reservation
450 Unable to process
451 Unable to retrieve client file
452 Use advance purchase arrival guarantee
453 Voucher number required
454 Wholesaler client file required
455 Wholesaler rate requires wholesaler client file
456 Work block is corrupted - cannot proceed
457 Need arrival information
458 Date outside inventory period
459 Invalid request code
503 Invalid form of deposit
504 Extra bed or crib not available
505 Invalid bed type
506 Credit card not accepted at property
507 Room type on request
558 Accounts are settled in a currency different from the quoted rate currency
559 Booking period restriction applies
560 Stay not compliant with availability restrictions
561 Loyalty program not found
562 Rate restricted
563 Closed to departure
564 Force sell restricted
565 Amount override restricted
566 Cancellation polices override restricted
567 Modification penalties apply
568 Cancellation penalties apply
569 Group booking required
570 Cannot cancel - arrival too close - call property
571 Travel agency name required
572 Company name required
573 Calendar availability is not supported by this external partner
574 Availability with pricing information is not supported by this external partner
575 Closed restriction
730 Invalid room type for requested hotel
731 Room type discontinued at this hotel
732 Invalid room type for rate requested
733 Restricted
734 Invalid corporate number for guarantee
735 Cancel hotel segments just booked, end and rebook
736 Address required for guarantee
737 System restricted
738 Form of deposit required for guarantee
739 Deposit not accepted within 72 hours
740 Guarantee required after 6pm arrival
741 Hotel requires guarantee
742 Corporate ID required
743 Invalid message length
744 Invalid field length
745 Invalid field ID
746 Name or frequent guest number required
747 Invalid frequent guest number - numeric only
748 Invalid corporate ID
749 Invalid address format
750 Invalid supplemental information
751 Adult rollaway number exceeds limit
752 Child rollaway number exceeds limit
753 Crib number exceeds limit
754 Extra adult number exceeds limit
755 Extra child number exceeds limit
756 IT number invalid
757 Unable to retrieve guest name record
758 Link process shut off
759 Confo nbr not received on modify, cancel or ignore
760 Must cancel/rebook property change
761 Frequent guest number cannot be changed
762 Corporate ID cannot be changed
763 Cannot modify name when frequent guest number present
764 Guest name may not be deleted
765 Phone may not be deleted
766 Advance deposit required for this hotel
767 Invalid room stay index
768 Inconsistent status
769 Only first reservation processed
770 Required data missing: reservation holder
772 Hotel geo-coding not yet available for country requested
773 Invalid length of parameter for search by address
774 Invalid format for search by address
775 Nothing found for requested criteria
776 Invalid length of parameter for search by availability status
777 Invalid format for search on availability status
778 No available or on request rooms found use search on all availability status
779 No available rooms found use search on all availability status
780 Invalid length of parameter for search by rate range
781 Invalid format for search by rate range
782 Rate exceeds maximum allowed for search by rate range
783 Room or rate not found
784 Time out Ð Please modify your request
785 Invalid length of parameter for search by distance
786 Invalid distance, maximum is 300
787 Search by distance does not contain a distance measure
788 Invalid format for search by distance
789 Hotel geo-coding not yet available for area requested
790 No properties found for reference point / distance requested
791 Search by distance and search by area code are mutually exclusive
792 Automatic search by distance ignored
793 Invalid Ð Use city code or search by reference point option
794 More hotels possible without automatic search by distance
795 No similar name found, see associated cities. More hotels possible without automatic search by distance option.
796 No match for reference point name option. Automatic search by distance ignored.
797 Geo-Coding not available for country requested automatic search by distance ignored
798 Geo-Coding not available for area requested automatic search by distance ignored
799 Invalid length of parameter for search by facilities
800 Invalid format for search by facilities
801 Invalid facility code requested
802 Invalid length of parameter for search by fire safety facilities
803 Invalid format for search by fire safety facilities
804 Invalid fire safety facility code requested
805 Invalid length of parameter for search by hotel category
806 Invalid format for search by hotel category
807 Invalid hotel category requested
808 Invalid length of parameter for search by hotel name
809 No similar name found see also associated cities
810 Invalid length of parameter for search by location
811 Nothing found for requested city
812 Location requested not in the system
813 Invalid length of parameter for search by phone number
814 Invalid format for search by phone number
815 Invalid length of parameter for search by reference point
816 Invalid format for search by reference point
817 Search by reference point and search by area are mutually exclusive
818 Automatic search by area ignored
819 Specify category in search by reference point or make a search for all reference point categories.
820 Invalid length of parameter for search by third party rating
821 Invalid format for search by third party rating
822 Invalid third party rating requested
823 Invalid length of parameter for search by transportation
824 Invalid format for search by transportation
825 Invalid transportation requested
826 Maximum number of transportation types is 3
827 Invalid length of parameter for search by zip code
828 Invalid area requested
829 Area identified can not be used twice
830 Invalid length of parameter for search by city
831 Invalid format for search by foreign currency
832 Invalid length of parameter for search by foreign currency
833 Invalid format for search by foreign currency
834 Search by lowest rate and search by biased display are mutually exclusive
835 Search by lowest rate and search by travel choice are mutually exclusive
836 Search by lowest rate and search by hotel name with ordering are mutually exclusive
837 Search by lowest rate and search by availability status are mutually exclusive
838 Invalid number of rooms in search by multiple identical room criteria
839 Invalid length of parameter for search by special rate
840 Duplicated rate codes
841 No available or on request rooms found, please use search on all availability status
842 Rate not loaded
843 Other rates available
844 Invalid length of parameter for search by hotel chain
845 Invalid number of hotel chain requested
846 Invalid format for search by hotel chain
847 Search by hotel chain and access qualifiers are mutually exclusive
848 Invalid type of access requested
849 Invalid number of access type requested
850 Non-existent service type
851 Non-existent service id
852 Invalid children ages
853 The feature penalty generation failed
854 Booking allotment blocking failed
855 Customer creation not authorized
856 Extra meal price information changed
857 Invalid extra meal
858 Change of commission not authorized
859 Invalid commission value
860 Passenger details error
861 No exact match for reference point name - use reference point list message
864 Special rate is required/missing

FOP Codes

Code Description
AX American Express
DC Diner's Club
DS Discover
CA MasterCard
VI Visa
CB Carte Blanche
ER Enroute
TP Universal Air Travel
JC JCB
AA American Airlines
DL Delta Equity
NW Northwest Airlines
TW TWA Getaway
UC United Travel Card
UA United Credit Card
EC EuroCard
CP Canadian Airlines
AS Alaska Air Barter
PO Purchase Order
AWRDCR Award Credit
DB Debit
PP This code indicates that the payment is through a deposit account/prepaid account/agency invoice. Only available if the Deposit Account ID field is filled out for the travel configuration.

Hotel Chain Codes

Code Description
6C Intercontinental Hotels Group
CW Carlson Brands (All)
EC Choice Brands
EH Hilton (All)
EM Marriott (All)
LQ La Quinta Inns
PH Preferred Hotels
SW Starwood (All)
TR Cendant Trip Rewards
WY Wyndham Hotels
ZZ Other/Unknown

AQC Codes

Code Description
1 Over 21
2 Over 65
3 Under 2
4 Under 12
5 Under 17
6 Under 21
7 Infant
8 Child
9 Teenager
10 Adult
11 Senior
12 Additional occupant with adult
13 Additional occupant without adult
14 Free child
15 Free adult
16 Young driver
17 Younger driver
18 Under 10
19 Junior

Supported Languages

Code Description
en-us English - American
en-au English - Australian
en-gb English - British
de German
fr French
fr-ca French - Quebecois
es Spanish
es-la Spanish - Latin American
pt-br Portuguese - Brazilian
nl Dutch
it Italian
sv Swedish
ja Japanese
cs Czech
da Danish
fi Finnish
el Greek
lv Latvian
lt Lithuanian
no Norwegian
sk Slovak
tr Turkish

ID Type Codes

Code Description
1 Customer
2 CRO (Customer Reservations Office)
3 Corporation representative
4 Company
5 Travel agency
6 Airline
7 Wholesaler
8 Car rental
9 Group
10 Hotel
11 Tour operator
12 Cruise line
13 Internet broker
14 Reservation
15 Cancellation
18 Other
21 Profile
25 Associated reservation
26 Associated itinerary reservation
27 Associated shared reservation
32 Merchant
33 Acquirer
34 Master reference
35 Purged master reference
36 Parent reference
37 Child reference
38 Linked reference
39 Contract
40 Confirmation number

Reservation Status Types

Code
Pending
Cancelled
Modified
Committed
Ignored
OnHold
Unsuccessful
PendingCancellation

Preference Levels

Value|Text Value|Description ---|--- 1|company_less_preferred|- 2|company_preferred|Two silver 3|company_most_preferred|- 4|less_preferred|- 5|preferred|- 10|most_preferred|Three golden diamonds

Hotel v1 - Post an availability search

This API has been deprecated.

Partners and customers using a deprecated API should contact SAP Concur and discuss moving to the latest versions.

Learn more in the API Lifecycle & Deprecation Policy.

Description

The following request is sent when the Travel user selects a hotel and searches for availability for a date range. The response includes the list of available rooms for the supplied date range.

Request

Content type

application/xml

Encoding

UTF-8

URI

The Hotel direct connect sends the relevant information to a URI that the travel supplier maintains. The standard location is:

https://{servername}/concur/hotel/v1/

The supplier determines the URI and provides it to SAP Concur to use when registering the partner application.

Authorization header

Authorization header with Basic credentials.

Request body root element

The request will contain a OTA_HotelAvailRQ parent element, containing the following attributes:

The OTA_HotelAvailRQ parent element contains the following child elements:

Element Name Required/Optional Data Type Description
POS Object The point of sale information.
AvailRequestSegments Array This parent element contains an AvailRequestSegment element for the requested availability.

POS child elements

Element Name Required/Optional Data Type Description
Source Object The source of the request. This element has the following attributes:
ISOCountry: The country code for the Travel user's home country.
ISOCurrency: The 3-letter ISO 4217 currency code for the Travel user's currency.

Source child elements

Element Name Required/Optional Data Type Description
RequestorID Object The corporate identifier. If necessary, multiple RequestorID elements can be sent. This element has the following attributes:
Type: The type code for the corporate identifier. Should be one of the supported ID Type Codes.
ID: The corporate identifier.
ID_Context: The corporate identifier context.

AvailRequestSegment

This parent element contains an AvailRequestSegment element for the requested availability.

Element Name Required/Optional Data Type Description
HotelSearchCriteria Object
StayDateRange Object This element contains the following attributes:
Start: The starting date of the requested date range. Format: YYYY-MM-DD
End: The ending date of the requested date range. Format: YYYY-MM-DD
RoomStayCandidates Array This parent element contains the RoomStayCandidate element. This element has a Quantity attribute indicating the number of guests. Currently only one guest is supported. The RoomStayCandidate element has a GuestCounts child element containing a GuestCount element. The GuestCount element has the following attributes:
AgeQualifyingCode: The value for this element should be 10, which represents an Adult guest.
Count: The number of guests included in the request.

HotelSearchCriteria child elements

Element Name Required/Optional Data Type Description
Criterion Object This parent element contains a HotelRef element for each hotel criterion used. Multiple criterion are compared using an OR comparison. The HotelRef element has the following attributes:
ChainCode: The hotel chain code.

XML Example Request

POST /concur/hotel/v1 HTTPS/1.1
Host: example.com
Authorization: Basic ...
Content-Type: application/xml
Content-Length: {length of content body}

<?xml version="1.0" encoding="utf-8" ?>
<OTA_HotelAvailRQ xmlns="http://www.opentravel.org/OTA/2003/05" EchoToken="ABC123" TimeStamp="2012-01-01T19:00:00" PrimaryLangID="en-us" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.opentravel.org/OTA/2003/05 ../Schemas/OTA_HotelAvailRQ.xsd" Version="1">
    <POS>
        <Source ISOCountry="US" ISOCurrency="USD">
            <RequestorID Type="18" ID="7777777" />
        </Source>
    </POS>
    <AvailRequestSegments>
        <AvailRequestSegment>
            <HotelSearchCriteria>
                <Criterion>
                    <HotelRef ChainCode="ZZ" HotelCode="HTL1111" />
                    <HotelRef ChainCode="ZZ" HotelCode="HTL2222" />
                </Criterion>
            </HotelSearchCriteria>
            <StayDateRange Start="2012-08-15" End="2010-08-17" />
            <RoomStayCandidates>
                <RoomStayCandidate Quantity="1">
                    <GuestCounts>
                        <GuestCount AgeQualifyingCode="10" Count="1" />
                    </GuestCounts>
                </RoomStayCandidate>
            </RoomStayCandidates>
        </AvailRequestSegment>
    </AvailRequestSegments>
</OTA_HotelAvailRQ>

Response

The supplier responds to the request by returning the details of the available room.

Content Types

application/xml

Content Body

The response will include a OTA_HotelAvailRS parent element, with the following attributes:

The OTA_HotelAvailRS parent element has the following child elements:

Element Name Required (must contain value)? Data Type Description
Success N This element is returned if the request was successful.
RoomStays Y Array This parent element contains a RoomStay parent element for each hotel room returned. Refer to the RoomStay child elements table for information about the child elements.
BasicPropertyInfo Y This element contains the HotelCode attribute, which contains the code for the hotel that this rate applies to.
TPA_Extensions N

RoomStay child elements

Element Name Required (must contain value)? Data Type Description
RatePlans Y The room rate plan. This parent element contains the following child element:
RatePlan: This element has the RatePlanCode attribute, defining the code for the room rate.
RoomRates This parent element has a RoomRate child element. The RoomRate element has a Rates child element.
BasicPropertyInfo Y This element contains the HotelCode attribute, which contains the code for the hotel that this rate applies to.
TPA_Extensions N This element contains the RequireSeriesCode child element, which has a value of true or false. This element indicates whether CVV should be queried and sent.

Rates child elements

Element Name Required (must contain value)? Data Type Description
Rate Object The supplied rate for the stay. If there are multiple rates for the stay, you can provide multiple Rate elements. The first one will be displayed to the user, with the rest available through the policy popup. This element has the following attributes:
EffectiveDate: The date the rate begins.
ExpireDate: The date that the rate expires.

Rate child elements

Element Name Required (must contain value)? Data Type Description
Base The rate details per day without tax. If the rate changes, provide the first day's rate. This element has the following attributes:
AmountBeforeTax: The rate amount per night before tax.
AmountAfterTax: The rate amount per night after tax.
CurrencyCode: The 3-letter ISO 4217 currency code for the room rate values.
RateDescription This parent element contains the Text child element, which contains the description of the rate.

TPA_Extensions child elements

Element Name Required (must contain value)? Data Type Description
RequireSeriesCode This element indicates whether CVV should be queried and sent. Format: true/false
GuaranteeRequired This element indicates whether the hotel requires a credit card deposit for this reservation. Possible values are:
always: When booking this rate, user will be asked for credit card (even if a deposit account is specified).
never: When booking this rate, user will not be asked for credit card (even if a deposit account is not specified).
default (or not present at all): When booking this rate, user will be asked for credit card if a deposit account is not specified.

XML Example of Successful Response

HTTPS/1.1 200 OK
Content-Type: application/xml
Content-Length: {length of content body}

<?xml version="1.0" encoding="utf-8" ?>
<OTA_HotelAvailRS xmlns="http://www.opentravel.org/OTA/2003/05" EchoToken="ABC123" TimeStamp="2012-01-01T19:00:00" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.opentravel.org/OTA/2003/05 ../Schemas/OTA_HotelAvailRS.xsd" Version="1">
    <Success />
    <RoomStays>
        <RoomStay>
            <RatePlans>
                <RatePlan RatePlanCode="2222222" />
            </RatePlans>
            <RoomRates>
                <RoomRate>
                    <Rates>
                        <Rate EffectiveDate="2012-08-15" ExpireDate="2010-08-17">
                            <Base AmountBeforeTax="100.00" AmountAfterTax="110.00" CurrencyCode="USD" />
                            <RateDescription>
                                <Text>CORPORATE RATE*KING</Text>
                            </RateDescription>
                        </Rate>
                    </Rates>
                </RoomRate>
            </RoomRates>
            <BasicPropertyInfo HotelCode="HTL1111" />
        </RoomStay>
        <RoomStay>
            <RatePlans>
                <RatePlan RatePlanCode="3333333" />
            </RatePlans>
            <RoomRates>
                <RoomRate>
                    <Rates>
                        <Rate EffectiveDate="2012-08-15" ExpireDate="2010-08-17">
                            <Base AmountBeforeTax="100.00" AmountAfterTax="110.00" CurrencyCode="USD" />
                            <RateDescription>
                                <Text>CORPORATE RATE*DOUBLE FREE INTERNET</Text>
                            </RateDescription>
                        </Rate>
                    </Rates>
                </RoomRate>
            </RoomRates>
            <BasicPropertyInfo HotelCode="HTL1111" />
        </RoomStay>
        <RoomStay>
            <RatePlans>
                <RatePlan RatePlanCode="4444444" />
            </RatePlans>
            <RoomRates>
                <RoomRate>
                    <Rates>
                        <Rate EffectiveDate="2012-08-15" ExpireDate="2010-08-17">
                            <Base AmountBeforeTax="100.00" AmountAfterTax="110.00" CurrencyCode="USD" />
                            <RateDescription>
                                <Text>REGULAR RATE*KING</Text>
                            </RateDescription>
                        </Rate>
                    </Rates>
                </RoomRate>
            </RoomRates>
            <BasicPropertyInfo HotelCode="HTL2222" />
            <TPA_Extensions>
                <RequireSeriesCode>true</RequireSeriesCode>
                <GuaranteeRequired>always</GuaranteeRequired>
            </TPA_Extensions>
        </RoomStay>
    </RoomStays>
</OTA_HotelAvailRS>

Hotel v1 - Post a booking rule search

This API has been deprecated.

Partners and customers using a deprecated API should contact SAP Concur and discuss moving to the latest versions.

Learn more in the API Lifecycle & Deprecation Policy.

Description

This request is sent when the Travel user selects a rate for the hotel. The response includes the rules for the specified rate.

Request

Encoding

UTF-8

URI

The Hotel direct connect sends the relevant information to a URI that the travel supplier maintains. The standard location is:

https://{servername}/concur/hotel/v1/

The supplier determines the URI and provides it to SAP Concur to use when registering the partner application.

Headers

Accept header

application/xml

Authorization header

Authorization header with Basic credentials. Required.

Request body

The request will contain a OTA_HotelBookingRuleRQ parent element, containing the following attributes:

The OTA_HotelBookingRuleRQ parent element contains the following child elements:

Element Description
POS The point of sale information. Contains a Source child element that specifies the source of the request. For information about Source element, see the Source elements table below.
RuleMessage This element has the HotelCode attribute. For information about the child element of this parent element, see the StatusApplication elements table below.

Source elements

The Source element has the following attributes:

The Source element contains the following element:

Element Description
RequestorID The corporate identifier. If necessary, multiple RequestorID elements can be sent. This element has the following attributes:
Type: The type code for the corporate identifier. Should be one of the supported ID Type Codes.
ID: The corporate identifier.
ID_Context: The corporate identifier context.

StatusApplication elements

This element has the following attributes:

XML Example Request

POST /concur/hotel/v1 HTTPS/1.1
Host: example.com
Authorization: Basic ...
Content-Type: application/xml
Content-Length: {length of content body}

<?xml version="1.0" encoding="UTF-8" ?>
<OTA_HotelBookingRuleRQ xmlns="http://www.opentravel.org/OTA/2003/05" EchoToken="ABC123" TimeStamp="2012-01-01T19:00:00" PrimaryLangID="en-us" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.opentravel.org/OTA/2003/05 ../Schemas/OTA_HotelBookingRuleRQ.xsd" Version="1">
    <POS>
        <Source ISOCountry="US" ISOCurrency="USD">
            <RequestorID Type="18" ID="7777777" />
        </Source>
    </POS>
    <RuleMessage HotelCode="HTL1111">
        <StatusApplication Start="2012-08-15" End="2010-08-17" RatePlanCode="HTL1_1" />
    </RuleMessage>
</OTA_HotelBookingRuleRQ>

Response

The supplier responds to the request by returning the details of the requested rate.

Content Types

application/xml

The response will include a OTA_HotelBookingRuleRS parent element, with the following attributes:

The OTA_HotelBookingRuleRS parent element contains a Success element if the request was successful. It also contains a RuleMessage element with the HotelCode and HotelName attributes. The RuleMessage element contains the following child elements:

| Element | Required (must contain value)? | Description |

|----------|---------|---------------------------------| | StatusApplication | Y | This element contains rate details. It has the following attributes:
Start: The start date of the request. Format: YYYY-MM-DD
End: The end date of the request. Format: YYYY-MM-DD
RatePlanCode: The rate plan code for the requested rate.

The StatusApplication element contains a RoomRates element with one RoomRate child element for each rate returned. For information about this element, see the RoomRate element table below. | | GuestCounts | Y | This parent element contains a GuestCount element with the following attributes:
AgeQualifyingCode: The value for this element should be 10, which represents an Adult guest.
Count: The number of guests included in the request. | | BookingRules | Y | This parent element contains a BookingRule element. For information about this child element, see the BookingRule element table below. |

RoomRate element

The RoomRate element has the following attributes:

The RoomRate element has the following child element:

Element Description
RateDescription This parent element contains a Text child element with text details of the room rate.

BookingRule element

Element Description
AcceptableGuarantees Information about acceptable guarantees. This element has an AcceptableGuarantee child element. For information about the AcceptableGuarantee element, see the AcceptableGuarantee element table below.
CancelPenalties This element has the CancelPenalty child element. The CancelPenalty element has the PenaltyDescription child element, containing a Text child element with the penalty description text.
RequiredPaymts This element contains the GuaranteePayment element, which has a PaymentCode attribute. The GuaranteePayment element contains the Description element, containing a Text child element with the required payment description text.

AcceptableGuarantee element

The AcceptableGuarantee element has the GuaranteeCode attribute and the following child element:

Element Description
GuaranteeDescription This element has the Text child element, containing the description of the guarantee.

XML Example of Successful Response

HTTPS/1.1 200 OK
Content-Type: application/xml
Content-Length: {length of content body}

<?xml version="1.0" encoding="UTF-8" ?>
<OTA_HotelBookingRuleRS xmlns="http://www.opentravel.org/OTA/2003/05" EchoToken="ABC123" TimeStamp="2012-01-01T19:00:00" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.opentravel.org/OTA/2003/05 ../Schemas/OTA_HotelBookingRuleRS.xsd" Version="1">
    <Success />
    <RuleMessage HotelCode="HTL1111" HotelName="HOTEL1">
        <StatusApplication Start="2012-08-15" End="2010-08-17" RatePlanCode="HTL1_1">
            <RoomRates>
                <RoomRate Amount="100.00" CurrencyCode="USD">
                    <RateDescription>
                        <Text>Standard Room</Text>
                    </RateDescription>
                </RoomRate>
            </RoomRates>
        </StatusApplication>
        <GuestCounts>
            <GuestCount AgeQualifyingCode="10" Count="1" />
        </GuestCounts>
        <BookingRules>
            <BookingRule>
                <AcceptableGuarantees>
                    <AcceptableGuarantee GuaranteeCode="1">
                        <GuaranteeDescription>
                            <Text>Credit Card WILL BE CHARGED IMMEDIATELY FOR THE FULL AMOUNT of the reservation.</Text>
                        </GuaranteeDescription>
                    </AcceptableGuarantee>
                </AcceptableGuarantees>
                <CancelPenalties>
                    <CancelPenalty>
                        <PenaltyDescription>
                            <Text>The hotel imposes the following cancellation penalty: Cancellations or changes made after 11:59 PM on Jun 18, 2012 are subject to a 1 Night Room and Tax penalty. The property makes no refunds for no shows or early checkouts.</Text>
                        </PenaltyDescription>
                    </CancelPenalty>
                </CancelPenalties>
                <RequiredPaymts>
                    <GuaranteePayment PaymentCode="2">
                        <Description>
                            <Text>Prepayment required</Text>
                        </Description>
                    </GuaranteePayment>
                </RequiredPaymts>
            </BookingRule>
        </BookingRules>
    </RuleMessage>
</OTA_HotelBookingRuleRS>

Hotel v1 - Post a hotel search

This API has been deprecated.

Partners and customers using a deprecated API should contact SAP Concur and discuss moving to the latest versions.

Learn more in the API Lifecycle & Deprecation Policy.

Description

This request is sent when the Travel user searches for hotels. The response includes the list of matching hotels for the given coordinates and radius. Hotel suppliers should return properties only in this area.

Request

Encoding

UTF-8

URI

The Hotel direct connect sends the relevant information to a URI that the travel supplier maintains. The standard location is:

https://{servername}/concur/hotel/v1/

The supplier determines the URI and provides it to SAP Concur to use when registering the partner application.

Request headers

Accept header

application/xml

Authorization header

Authorization header with Basic credentials. Required.

Request body

The request will contain a OTA_HotelSearchRQ parent element, containing the following attributes:

The OTA_HotelSearchRQ parent element contains the following child elements:

Element Description
POS The point of sale information. Contains a Source child element that specifies the source of the request. For information about Source element, see the Source elements table below.
Criteria The search criteria provided by the customer. This parent element contains a Criterion child element. For information about this child element, see the Criterion elements table below.

Source elements

The Source element specifies the source of the request. It has the following attributes:

The Source element contains the following element:

Element Description
RequestorID The corporate identifier. If necessary, multiple RequestorID elements can be sent. This element has the following attributes:
Type: The type code for the corporate identifier. Should be one of the supported ID Type Codes.
ID: The corporate identifier.
ID_Context: The corporate identifier context.

Criterion elements

Element Description
Position The hotel search center position. Position is sent all the time and is in LatLon format (degrees as float numbers). It should be used as position source for actual search. This element has two attributes:
Latitude: The latitude at the center of the hotel search.
Longitude: The longitude at the center of the hotel search.
Address The address information for the hotel search. Optional. For information about the child elements of this parent element, see the Address elements table below.
RefPoint The reference point for the search. Optional. This element has the Name attribute, containing the location city, state and country. Example: Redmond, WA, USA
HotelRef The hotel information. Optional. This element can have the following attribute:
HotelName: The hotel name supplied by the customer. This attribute only appears if the customer provided a name. This value should be interpreted as a "contains" style match.
Radius The hotel search radius from the starting position. This element has three possible attributes:
Distance: The distance to search from the defined center.
DistanceMeasure: The unit of measurement to use when calculating the search radius with the Distance value. Values: Miles = M, Kilometers = K. If not included, the following attribute should be used:
UnitOfMeasureCode: The code for the unit of measure. Values: Miles = 2, Kilometers = 1

NOTE: Only return hotels within this search radius. You can use a simple box search.
StayDateRange The date range to search for. Contains the Start and End attributes. Format: YYYY-MM-DD

Address elements

Element Description
CityName The name of the city the user is searching in.
CountryName This element has the Code attribute, containing the two character country code for the country the user is searching in.

XML Example Request

POST /concur/hotel/v1 HTTPS/1.1
Host: example.com
Authorization: Basic ...
Content-Type: application/xml
Content-Length: {length of content body}

<OTA_HotelSearchRQ xmlns="http://www.opentravel.org/OTA/2003/05" EchoToken="ABC123" TimeStamp="2012-01-01T19:00:00" PrimaryLangID="en-us" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.opentravel.org/OTA/2003/05 ../Schemas/OTA_HotelSearchRQ.xsd" Version="6.000">
    <POS>
        <Source ISOCountry="US" ISOCurrency="USD">
            <RequestorID Type="4" ID="7777777" ID_Context="MyHotel" />
        </Source>
    </POS>
    <Criteria>
        <Criterion>
            <Position Latitude="45.1317" Longitude="-86.1823" />
            <Address>
                <CityName>Empire</CityName>
                <CountryName Code="US" />
            </Address>
            <RefPoint Name="Empire, MI, USA" />
            <HotelRef HotelName="Inn" />
            <Radius Distance="5" DistanceMeasure="M" />
            <StayDateRange Start="2012-08-15" End="2010-08-17" />
        </Criterion>
    </Criteria>
</OTA_HotelSearchRQ>

Response

The supplier responds to the request by returning the list of possible search matches, with a maximum result set of 1000 results.

Content Types

application/xml

Response body

The response will include a OTA_HotelSearchRS parent element, with the following attributes:

The OTA_HotelSearchRS parent element contains the following child elements:

Element Required (must contain value)? Description
Success N This element is returned if the request was successful.
Properties This element contains a Property parent element for each hotel property returned. For information about the child elements of this parent element, see the Property elements table below.

Property elements

The Property element has the following attributes:

The Property element has the following child elements:

Element Description
Position The hotel position. This element has two attributes:
Latitude: The latitude of the hotel.
Longitude: The longitude of the hotel.
Address The address of the hotel. Optional. Provide this element if you would like the address to display in the search results. For information about the child elements of this parent element, see the Address elements table below.
TPA_Extensions For information about the child elements of this parent element, see the TPA_Extensions elements table below.

Address elements

Element Description
StreetNmbr The street address of the hotel.
CityName The city the hotel is in.
PostalCode The postal code of the hotel.
CountryName This element has the Code attribute, which contains the country code of the hotel.

TPA_Extensions elements

Element Description
HotelImageURI The link to the image associated with the hotel. A fully qualified url to the hotel image should be returned in the response. Image size must be 70 pixels wide and 72 pixels tall. Images can be no larger than 8K bytes. The image format must be gif or jpg. Images should be accessible through http and https protocols.
HotelPreference This element includes the customer's preference level for the individual property. Refer to the Hotel Direct Connect Codes for the possible values.
GDS_InfoType This parent element has a MasterChainCode attribute, containing the two-letter GDS code that gives access to a number of different hotel brands owned or represented by the same chain. The MasterChainCode lets Concur automatically determine what advantage card numbers to send for this hotel. Refer to the Hotel Direct Connect Codes. This parent element contains a GDS_Codes element, which contains a GDS_Code element. The GDS_Code element has the following attributes:
GDS_PropertyCode: This attribute lets Concur match against other results (to display GDS and HotelService rates as one item). The most typical one is Northstar ID. If GDS_PropertyCode is provided, GDS_Name must also be provided
GDS_Name: The name of the associated GDS.
StarRating The number of stars the hotel is rated for. Optional. Possible values: 1-5

XML Example of Successful Response

HTTPS/1.1 200 OK
Content-Type: application/xml
Content-Length: {length of content body}

<OTA_HotelSearchRS xmlns="http://www.opentravel.org/OTA/2003/05" EchoToken="ABC123" TimeStamp="2012-01-01T19:00:00" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.opentravel.org/OTA/2003/05 ../Schemas/OTA_HotelSearchRS.xsd" Version="6.000">
    <Success />
    <Properties>
        <Property ChainCode="ZZ" HotelCode="HTL1111" HotelName="HOTEL1">
            <Position Latitude="45.132" Longitude="-86.1823"/>
            <Address>
                <StreetNmbr>123 Lake avenue</StreetNmbr>
                8/33
                <CityName>Empire</CityName>
                <PostalCode>12345</PostalCode>
                <CountryName Code="US"/>
            </Address>
            <TPA_Extensions>
                <HotelImageURI>http://www.c.com/h/HTL1.gif</HotelImageURI>
                <HotelPreference>preferred</HotelPreference>
                <GDS_InfoType MasterChainCode="ZZ">
                    <GDS_Codes>
                        <GDS_Code GDS_PropertyCode="W1234567" GDS_Name="Worldspan"/>
                    </GDS_Codes>
                </GDS_InfoType>
                <StarRating>4</StarRating>
            </TPA_Extensions>
        </Property>
        <Property ChainCode="ZZ" HotelCode="HTL2222" HotelName="HOTEL2">
            <Position Latitude="45.131" Longitude="-86.1823"/>
            <Address>
                <StreetNmbr>124 Lake avenue</StreetNmbr>
                <CityName>Empire</CityName>
                <PostalCode>12345</PostalCode>
                <CountryName Code="US"/>
            </Address>
        </Property>
        <Property ChainCode="ZZ" HotelCode="HTL3333" HotelName="HOTEL3">
            <Position Latitude="45.1317" Longitude="-86.182"/>
            <Address>
                <StreetNmbr>125 Lake avenue</StreetNmbr>
                <CityName>Empire</CityName>
                <PostalCode>12345</PostalCode>
                <CountryName Code="US"/>
            </Address>
        </Property>
    </Properties>
</OTA_HotelSearchRS>

Hotel v1 - Post a new reservation

This API has been deprecated.

Partners and customers using a deprecated API should contact SAP Concur and discuss moving to the latest versions.

Learn more in the API Lifecycle & Deprecation Policy.

Description

This request is sent when the Travel user creates a reservation for the supplied hotel. The response includes the reservation details.

Request

Encoding

UTF-8

URI

The Hotel direct connect sends the relevant information to a URI that the travel supplier maintains. The standard location is:

https://{servername}/concur/hotel/v1/

The supplier determines the URI and provides it to SAP Concur to use when registering the partner application.

Headers

Accept header

application/xml

Authorization header

Authorization header with Basic credentials. Required.

Request body

The request will contain a OTA_HotelResRQ parent element, containing the following attributes:

The OTA_HotelResRQ parent element contains the following child elements:

Element Description
POS The point of sale information. Contains a Source child element that specifies the source of the request. For information about Source element, see the Source elements table below.
HotelReservations This element has a HotelReservation child element. For information about the HotelReservation element, see the HotelReservation elements table below.

Source elements

The Source element has the following attributes:

The Source element contains the following element:

Element Description
RequestorID The corporate identifier. If necessary, multiple RequestorID elements can be sent. This element has the following attributes:
Type: The type code for the corporate identifier. Should be one of the supported ID Type Codes.
ID: The corporate identifier.
ID_Context: The corporate identifier context.

HotelReservation elements

Element Description
RoomStays This parent element contains the RoomStay child element. For information about the RoomStay element, see the RoomStay elements table below.
ResGuests This parent element contains the ResGuest element. The ResGuest element contains the Profiles element. The Profiles element contains the ProfileInfo element, which contains a Profile child element for each guest. The Profile child element contains the Customer parent element; for information about the Customer element, see the Customer elements table below.
ResGlobalInfo This parent element contains a Memberships child element. This element contains a Membership child element with the following attributes:
ProgramCode: The name of the membership program.
AccountID: The account number for the membership program.
TPA_Extensions This parent element contains a CustomFields element that contains a CustomField element for each custom field in the request. The CustomField elements have the following attributes:
Name: The name of the custom field.
Type: The type of information the custom field contains.

NOTE: Some of the regular profile fields can be included in the CustomField elements. Their Type = Profile. Supported fields are: Cost Center, Employee ID, Manager, Employee Title, Organization Unit and XML Sync ID. Sharing the profile item has to be enabled for the vendor (vendor requests these values), then it can be enabled in specific travel configurations (customer wants to share the items with the vendor).

RoomStay Request elements

Element Description
RoomTypes This parent element contains the RoomType child element, with the NumberofUnits attribute indicating how many rooms of this type are included in the reservation.
RatePlans This parent element contains the RatePlan child element, with the RatePlanCode attribute, specifying the rate plan code for the reservation.
GuestCounts This parent element contains the GuestCount child element, with the following attributes:
AgeQualifyingCode: The value for this element should be 10, which represents an Adult guest.
Count: The number of guests included in the request.
TimeSpan This element has the following attributes:
Start: The start date of the reservation.
End: The end date of the reservation.
Guarantee This parent element contains the GuaranteesAccepted element. The GuaranteesAccepted element contains the GuaranteeAccepted element. This element has the GuaranteeTypeCode attribute, specifying the type of guarantee placed on the reservation. The GuaranteeAccepted parent element has a PaymentCard child element for card guarantees; for information about this child element, see the PaymentCard elements table below.
BasicPropertyInfo This element contains the HotelCode attribute.
Comments The comments on the reservation. This parent element contains a Comment child element for each comment associated with the reservation.

Customer elements

Element Description
PersonName This element contains the following child elements:
NamePrefix: The user's name prefix.
GivenName: The user's given name.
Surname: The user' surname.
Telephone This element has a PhoneNumber attribute containing the guests' phone number.
Email The guest's email address.
Address This parent element has the following child elements:
AddressLine: The first address line.
CityName: The address city.
PostalCode: The address postal code.
StateProv: The address state/province.
CountryName: The 3-character address country name. Format: USA

PaymentCard elements

The PaymentCard element has the following attributes:

The PaymentCard element has the following child elements:

Element Description
CardHolderName The card holder's name.
Address The billing address of the card. This parent element contains the following child elements:
AddressLine: The first address line.
CityName: The address city.
PostalCode: The address postal code.
StateProv: The address state/province.
CountryName: The 2-character address country name. Format: US

XML Example Request

POST /concur/hotel/v1 HTTPS/1.1
Host: example.com
Authorization: Basic ...
Content-Type: application/xml
Content-Length: {length of content body}

<?xml version="1.0" encoding="UTF-8" ?>
<OTA_HotelResRQ xmlns="http://www.opentravel.org/OTA/2003/05" EchoToken="ABC123" TimeStamp="2012-01-01T19:00:00" PrimaryLangID="en-us" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.opentravel.org/OTA/2003/05 ../Schemas/OTA_HotelResRQ.xsd" Version="1">
    <POS>
        <Source ISOCountry="US" ISOCurrency="USD">
            <RequestorID Type="18" ID="7777777" />
        </Source>
    </POS>
    <HotelReservations>
        <HotelReservation>
            <RoomStays>
                <RoomStay>
                    <RoomTypes>
                        <RoomType NumberOfUnits="1" />
                    </RoomTypes>
                    <RatePlans>
                        <RatePlan RatePlanCode="222222" />
                    </RatePlans>
                    <GuestCounts>
                        <GuestCount AgeQualifyingCode="10" Count="1" />
                    </GuestCounts>
                    <TimeSpan Start="2012-08-15" End="2010-08-17" />
                    <Guarantee>
                        <GuaranteesAccepted>
                            <GuaranteeAccepted GuaranteeTypeCode="CC">
                                <PaymentCard CardCode="AX" ExpireDate="1215" SeriesCode="1234">
                                    <CardHolderName>CHRIS MILLER</CardHolderName>
                                    <Address>
                                        <AddressLine>18400 NE UNION HILL RD.</AddressLine>
                                        <CityName>REDMOND</CityName>
                                        <PostalCode>98052</PostalCode>
                                        <StateProv>WA</StateProv>
                                        <CountryName>US</CountryName>
                                    </Address>
                                </PaymentCard>
                            </GuaranteeAccepted>
                        </GuaranteesAccepted>
                    </Guarantee>
                    <BasicPropertyInfo HotelCode="HTL1111" />
                    <Comments>
                        <Comment>NON-SMOKING</Comment>
                        <Comment>not close to the elevator</Comment>
                    </Comments>
                </RoomStay>
            </RoomStays>
            <ResGuests>
                <ResGuest>
                    <Profiles>
                        <ProfileInfo>
                            <Profile>
                                <Customer>
                                    <PersonName>
                                        <NamePrefix>Mr.</NamePrefix>
                                        <GivenName>CHRIS</GivenName>
                                        <Surname>MILLER</Surname>
                                    </PersonName>
                                    <Telephone PhoneNumber="212-555-1212" />
                                    <Email>cmiller@example.com</Email>
                                    <Address>
                                        <AddressLine>18400 NE Union Hill Rd.</AddressLine>
                                        <CityName>Redmond</CityName>
                                        <PostalCode>98052</PostalCode>
                                        <StateProv>WA</StateProv>
                                        <CountryName>USA</CountryName>
                                    </Address>
                                </Customer>
                            </Profile>
                        </ProfileInfo>
                    </Profiles>
                </ResGuest>
            </ResGuests>
            <ResGlobalInfo>
                <Memberships>
                    <Membership ProgramCode="HotelLoyaltyProgram" AccountID="987654321" />
                </Memberships>
            </ResGlobalInfo>
            <TPA_Extensions>
                <CustomFields>
                    <CustomField Name="OrgUnit" Type="Profile">Sales</CustomField>
                    <CustomField Name="XmlSyncId" Type="Profile">9293kks8drf6s8f</CustomField>
                </CustomFields>
            </TPA_Extensions>
        </HotelReservation>
    </HotelReservations>
</OTA_HotelResRQ>

Response

The supplier responds to the request by returning the details of the completed booking.

Content Types

application/xml

Response body

The response will include a OTA_HotelResRS parent element, with the following attributes:

The OTA_HotelResRS parent element contains the following child elements:

Element Required? Description
Success N This element is returned if the request was successful.
HotelReservations Y This element has a HotelReservation child element. For information about the HotelReservation element, see the HotelReservation elements table below.

HotelReservation elements

Element Description
RoomStays This parent element contains the RoomStay child element. For information about the RoomStay element, see the RoomStay Response elements table below.
ResGuests This parent element contains the ResGuest element. For information about the ResGuest element, see the ResGuest Response elements table below.
ResGlobalInfo This parent element contains a HotelReservationIDs parent element, which contains a HotelReservationID child element with the ResID_Value attribute, identifying the reservation.
TPA_Extensions This parent element contains a VoucherURL child element. If you need to provide some voucher or certificate of purchase, please publish it on your server and provide the URL in the VoucherURL element.

RoomStay Response elements

Element Description
RoomTypes This parent element contains the RoomType child element, with the NumberofUnits attribute indicating how many rooms of this type are included in the reservation. The RoomType parent element has the RoomDescription child element. The RoomDescription element contains the Text element describing the room.
RatePlans This parent element contains the RatePlan child element, with the RatePlanCode attribute, specifying the rate plan code for the reservation. For information about the RatePlan element, see the RatePlan elements table below.
RoomRates This parent element contains the RoomRate element, with a RatePlanCode attribute. The RoomRate element contains a Rates parent element, with a Rate child element for each included rate. The Rate is for each day, not the total rate. For information about the Rate element, see the Rate elements table below.
GuestCounts This element contains a GuestCount element with the following attributes:
AgeQualifyingCode: The value for this element should be 10, which represents an Adult guest.
Count: The number of guests included in the request.
TimeSpan This element has the following attributes:
Start: The start date of the reservation.
End: The end date of the reservation.
BasicPropertyInfo This element contains the HotelCode and HotelName attributes. The BasicPropertyInfo parent element has an Address child element. For information about the Address element, see the Address elements table below.

RatePlan elements

Element Description
CancelPenalties This element contains the CancelPenalty parent element. The CancelPenalty element contains the PenaltyDescription element, with a Text child element containing the cancellation penalty text.
RatePlanDescription This element contains a Text child element with the text description of the rate plan.

Rate elements

The Rate element has the following attributes:

The Rate element contains the following child elements:

Element Description
Base The base rate amount. This element contains the following attributes:
AmountAfterTax: The rate amount with all taxes included.
CurrencyCode: The 3-letter ISO 4217 currency code for the rate amount.

The Base element contains the Taxes child element. The Taxes element contains a Tax element for each included tax, with the following attributes:
Amount: The amount of the tax.
CurrencyCode: The The 3-letter ISO 4217 currency code for the tax amount.

The Tax element contains a TaxDescription parent element, with a Text child element containing the tax description text.

Address elements

Element Description
AddressLine The first address line.
CityName The address city.
PostalCode The address postal code.
CountryName The 3-character address country name. Format: USA

ResGuest Response elements

The ResGuest response parent element contains the ProfileInfo child element. The ProfileInfo element has the Profile child element. The Profile element contains the Customer element. The Customer element contains the PersonName element. The PersonName element contains the following child elements:

Element Description
NamePrefix The guest's name prefix.
GivenName The guest's first name.
Surname The guest's last name.

XML Example of Successful Response

HTTPS/1.1 200 OK
Content-Type: application/xml
Content-Length: {length of content body}

<?xml version="1.0" encoding="utf-8" ?>
<OTA_HotelResRS
  xmlns="http://www.opentravel.org/OTA/2003/05" EchoToken="ABC123" ResResponseType="Committed" TimeStamp="2012-01-01T19:00:00" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.opentravel.org/OTA/2003/05 ../Schemas/OTA_HotelResRS.xsd" Version="1">
    <Success />
    <HotelReservations>
        <HotelReservation>
            <RoomStays>
                <RoomStay>
                    <RoomTypes>
                        <RoomType NumberOfUnits="1">
                            <RoomDescription>
                                <Text>Standard Room</Text>
                            </RoomDescription>
                        </RoomType>
                    </RoomTypes>
                    <RatePlans>
                        <RatePlan RatePlanCode="2222222">
                            <CancelPenalties>
                                <CancelPenalty>
                                    <PenaltyDescription>
                                        <Text>The hotel imposes the following cancellation penalty: Cancellations or changes made after 11:59 PM on Jun 18, 2012 are subject to a 1 Night Room and Tax penalty. The property makes no refunds for no shows or early checkouts.</Text>
                                    </PenaltyDescription>
                                </CancelPenalty>
                            </CancelPenalties>
                            <RatePlanDescription>
                                <Text>Standard Room</Text>
                            </RatePlanDescription>
                        </RatePlan>
                    </RatePlans>
                    <RoomRates>
                        <RoomRate RatePlanCode="2222222">
                            <Rates>
                                <Rate EffectiveDate="2012-08-15" ExpireDate="2012-08-17">
                                    <Base AmountAfterTax="100.00" CurrencyCode="USD">
                                        <Taxes>
                                            <Tax Amount="10.00" CurrencyCode="USD">
                                                <TaxDescription>
                                                    <Text>VAT</Text>
                                                </TaxDescription>
                                            </Tax>
                                        </Taxes>
                                    </Base>
                                </Rate>
                                <Rate EffectiveDate="2012-08-15" ExpireDate="2012-08-15">
                                    <Base AmountAfterTax="100.00" CurrencyCode="USD" />
                                </Rate>
                                <Rate EffectiveDate="2012-08-16" ExpireDate="2012-08-16">
                                    <Base AmountAfterTax="110.00" CurrencyCode="USD" />
                                </Rate>
                            </Rates>
                        </RoomRate>
                    </RoomRates>
                    <GuestCounts>
                        <GuestCount AgeQualifyingCode="10" Count="1" />
                    </GuestCounts>
                    <TimeSpan Start="2012-08-15" End="2010-08-17" />
                    <BasicPropertyInfo HotelCode="HTL1111" HotelName="Hotel Deluxe">
                        <Address>
                            <AddressLine>123 HOTEL ST</AddressLine>
                            <CityName>HOTELTOWN</CityName>
                            <PostalCode>12344</PostalCode>
                            <CountryName>USA</CountryName>
                        </Address>
                    </BasicPropertyInfo>
                </RoomStay>
            </RoomStays>
            <ResGuests>
                <ResGuest>
                    <Profiles>
                        <ProfileInfo>
                            <Profile>
                                <Customer>
                                    <PersonName>
                                        <NamePrefix>Mr.</NamePrefix>
                                        <GivenName>CHRIS</GivenName>
                                        <Surname>MILLER</Surname>
                                    </PersonName>
                                </Customer>
                            </Profile>
                        </ProfileInfo>
                    </Profiles>
                </ResGuest>
            </ResGuests>
            <ResGlobalInfo>
                <HotelReservationIDs>
                    <HotelReservationID ResID_Value="888000888" />
                </HotelReservationIDs>
            </ResGlobalInfo>
            <TPA_Extensions>
                <CustomFields>
                    <CustomField Name="OrgUnit" Type="Profile">Sales</CustomField>
                    <CustomField Name="XmlSyncId" Type="Profile">9293kks8drf6s8f</CustomField>
                </CustomFields>
            </TPA_Extensions>
        </HotelReservation>
    </HotelReservations>
</OTA_HotelResRS>

Hotel v1 - Post a reservation cancellation

This API has been deprecated.

Partners and customers using a deprecated API should contact SAP Concur and discuss moving to the latest versions.

Learn more in the API Lifecycle & Deprecation Policy.

Description

This request is sent when the Travel user cancels their reservation. The response includes the reservation cancellation code.

Request

Encoding

UTF-8

URI

The Hotel direct connect sends the relevant information to a URI that the travel supplier maintains. The standard location is:

https://{servername}/concur/hotel/v1/

The supplier determines the URI and provides it to SAP Concur to use when registering the partner application.

Request headers

Accept header

application/xml

Authorization header

Authorization header with Basic credentials. Required.

Request body

The request will contain a OTA_CancelRQ parent element, containing the following attributes:

The OTA_CancelRQ parent element contains the following child elements:

Element Description
POS The point of sale information. Contains a Source child element that specifies the source of the request. For information about Source element, see the Source elements table below.
UniqueID This element has the following attributes:
ID: The reservation identification number.
Type: The type of reservation.

Source elements

The Source element specifies the source of the request. It has the following attributes:

The Source element contains the following element:

Element Description
RequestorID The corporate identifier. If necessary, multiple RequestorID elements can be sent. This element has the following attributes:
Type: The type code for the corporate identifier. Should be one of the supported ID Type Codes.
ID: The corporate identifier.
ID_Context: The corporate identifier context.

XML Example Request

POST /concur/hotel/v1 HTTPS/1.1
Host: example.com
Authorization: Basic ...
Content-Type: application/xml
Content-Length: {length of content body}

<?xml version="1.0" encoding="utf-8" ?>
<OTA_CancelRQ CancelType="Cancel" xmlns="http://www.opentravel.org/OTA/2003/05" EchoToken="ABC123" TimeStamp="2012-01-01T19:00:00" PrimaryLangID="en-us" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.opentravel.org/OTA/2003/05 ../Schemas/OTA_CancelRQ.xsd" Version="1">
    <POS>
        <Source ISOCountry="US" ISOCurrency="USD">
            <RequestorID Type="18" ID="7777777" />
        </Source>
    </POS>
    <UniqueID ID="888000888" Type="14" />
</OTA_CancelRQ>

Response

The supplier responds to the request by returning the details of the completed booking.

Content Types

application/xml

Response body

The response includes an OTA_CancelRS parent element with the following attributes:

The OTA_CancelRS parent element contains a Success element if the request was successful. It also contains the following child elements:

Element Description
UniqueID This parent element has the following attributes:
ID: The ID of the cancelled reservation.
Type: Any number can be supplied in this attribute.
CancelInfoRS This element has a UniqueID child element with the following attributes:
ID: The hotel cancellation number.
Type: Value for cancellation number should be 15, confirmation number 14.

XML Example Request

HTTPS/1.1 200 OK
Content-Type: application/xml
Content-Length: {length of content body}

<?xml version="1.0" encoding="utf-8" ?>
<OTA_CancelRS Status="Cancelled" xmlns="http://www.opentravel.org/OTA/2003/05" EchoToken="ABC123" TimeStamp="2012-01-01T19:00:00" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.opentravel.org/OTA/2003/05 ../Schemas/OTA_CancelRS.xsd" Version="1">
    <Success />
    <UniqueID ID="888000888" Type="14" />
    <CancelInfoRS>
        <UniqueID ID="1010010000" Type="14" />
    </CancelInfoRS>
</OTA_CancelRS>

Hotel v1 - Post a reservation query

This API has been deprecated.

Partners and customers using a deprecated API should contact SAP Concur and discuss moving to the latest versions.

Learn more in the API Lifecycle & Deprecation Policy.

Description

This request is sent when the Travel user requests the reservation details for the supplied reservation ID. The response includes the reservation details, and is identical to the Post New Reservation response.

Request

Encoding

UTF-8

URI

The Hotel direct connect sends the relevant information to a URI that the travel supplier maintains. The standard location is:

https://{servername}/concur/hotel/v1/

The supplier determines the URI and provides it to SAP Concur to use when registering the partner application.

Headers

Accept header

application/xml

Authorization header

Authorization header with Basic credentials. Required. Refer to the Security documentation for more information.

Request body

The request will contain a OTA_ReadRQ parent element, containing the following attributes:

The OTA_ReadRQ parent element contains the following child elements:

Element Description
POS The point of sale information. Contains a Source child element that specifies the source of the request. For information about Source element, see the Source elements table below.
ReadRequests This element has a ReadRequest child element. For information about the ReadRequest element, see the ReadRequest elements table below.

Source elements

The Source element has the following attributes:

The Source element contains the following element:

Element Description
RequestorID The corporate identifier. If necessary, multiple RequestorID elements can be sent. This element has the following attributes:
Type: The type code for the corporate identifier. Should be one of the supported ID Type Codes.
ID: The corporate identifier.
ID_Context: The corporate identifier context.

ReadRequest elements

Element Description
UniqueID This element has the following attributes:
ID: The reservation identification number.
Type: The type of reservation.
Verification This parent element contains information that can be used to verify the owner of the reservation. For information about the Verification element, see the Verification elements table below.

Verification elements

Element Description
PersonName This parent element contains the GivenName and SurName child elements, which should match the reservation details.
TelephoneInfo This element has the PhoneNumber attribute, which contains the guest telephone number. The number should match the reservation.

XML Example Request

POST /concur/hotel/v1 HTTPS/1.1
Host: example.com
Authorization: Basic ...
Content-Type: application/xml
Content-Length: {length of content body}

<?xml version="1.0" encoding="utf-8" ?>
<OTA_ReadRQ xmlns="http://www.opentravel.org/OTA/2003/05" EchoToken="ABC123" TimeStamp="2012-01-01T19:00:00" PrimaryLangID="en-us" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.opentravel.org/OTA/2003/05 ../Schemas/OTA_ReadRQ.xsd" Version="1">
    <POS>
        <Source ISOCountry="US" ISOCurrency="USD">
            <RequestorID Type="18" ID="7777777" />
        </Source>
    </POS>
    <ReadRequests>
        <ReadRequest>
            <UniqueID ID="888000888" Type="14" />
            <Verification>
                <PersonName>
                    <GivenName>CHRIS</GivenName>
                    <Surname>MILLER</Surname>
                </PersonName>
                <TelephoneInfo PhoneNumber="212-555-1212" />
            </Verification>
        </ReadRequest>
    </ReadRequests>
</OTA_ReadRQ>

Response

The supplier responds to the request by returning the details of the completed booking.

Content Types

application/xml

Response body

The response is identical to the response for Post New Reservation.

Hotel v1 - Post a reservation update

This API has been deprecated.

Partners and customers using a deprecated API should contact SAP Concur and discuss moving to the latest versions.

Description

NOTE: This function is not supported in the current version. Support may be returned in a future release.

This request is sent when the Travel user updates their reservation. The response includes the new reservation identifier.

Request

Encoding

UTF-8

Request URI

The Hotel direct connect sends the relevant information to a URI that the travel supplier maintains. The standard location is:

https://{servername}/concur/hotel/v1/

The URI is configured by the supplier when registering the partner application.

Headers

Accept header

application/XML

Authorization header

Authorization header with Basic credentials.

Request Body

The request will contain an OTA_HotelResModifyRQ parent element, with the following attributes:

The OTA_HotelResModifyRQ element contains the following child elements:

Element Description
POS The point of sale information. Contains a Source child element that specifies the source of the request. For information about Source element, see the Source elements table below.
HotelResModifies This element has a HotelResModify child element. For more information about this child element, see the HotelResModify element table below.

Source elements

The Source element has the following attributes:

The Source element contains the following element:

Element Description
RequestorID The customer's identifiers. If necessary, multiple RequestorID elements can be sent. This element has the following attributes:
Type: The code for the customer type.
ID: The identifier for the user.

HotelResModify element

The HotelResModify element with the following attributes:

The HotelResModify element contains the following child elements:

Element Description
RoomStays This parent element contains the RoomStay element. Refer to the RoomStay Request elements table for information about child elements.
ResGuests This parent element contains the ResGuest element. For more information about this child element, see the ResGuest elements table below.
ResGlobalInfo This parent element contains a HotelReservationIDs child element. This element contains a HotelReservationID child element with the following attribute:
ResID_Value: The reservation ID.

RoomStay Request elements

Element Description
RoomTypes This parent element contains the RoomType child element, with the NumberofUnits attribute indicating how many rooms of this type are included in the reservation.
RatePlans This parent element contains the RatePlan child element, with the RatePlanCode attribute, specifying the rate plan code for the reservation.
GuestCounts This parent element contains the GuestCount child element, with the following attributes:
AgeQualifyingCode: The value for this element should be 10, which represents an Adult guest.
Count: The number of guests included in the request.
TimeSpan This element has the following attributes:
Start: The start date of the reservation.
End: The end date of the reservation.
Guarantee This parent element contains the GuaranteesAccepted element. The GuaranteesAccepted element contains the GuaranteeAccepted element. This element has the GuaranteeTypeCode attribute, specifying the type of guarantee placed on the reservation. The GuaranteeAccepted parent element has a PaymentCard child element for card guarantees; for information about this child element, see the PaymentCard elements table below.
BasicPropertyInfo This element contains the HotelCode attribute.
Comments The comments on the reservation. This parent element contains a Comment child element for each comment associated with the reservation.

ResGuest elements

The ResGuest element has the following attributes:

The ResGuest element contains a Profiles child element with information about the guest's profile. The Profiles element contains the ProfileInfo child element. The ProfileInfo element has the Profile child element. The Profile element contains the Customer element. The Customer element contains the following child elements:

Element Description
PersonName This element contains the following child elements:
GivenName: The guest's given name.
Surname: The guest's surname.
Telephone This element has a PhoneNumber attribute containing the guest's phone number.
Email The guest's email address.
Address This parent element has the following child elements:
AddressLine: The first address line.
CityName: The address city.
PostalCode: The address postal code.
StateProv: The address state/province.
CountryName: The 2-character address country name. Format: US

PaymentCard elements

The PaymentCard element has the following attributes:

The PaymentCard element has the following child elements:

Element Description
CardHolderName The card holder's name.
Address The billing address of the card. This parent element contains the following child elements:
AddressLine: The first address line.
CityName: The address city.
PostalCode: The address postal code.
StateProv: The address state/province.
CountryName: The 2-character address country name. Format: US

XML Example Request

POST /concur/hotel/v1 HTTPS/1.1
Host: example.com
Authorization: Basic ...
Content-Type: application/xml
Content-Length: {length of content body}

<?xml version="1.0" encoding="UTF-8" ?>
<OTA_HotelResModifyRQ xmlns="http://www.opentravel.org/OTA/2003/05" EchoToken="ABC123" TimeStamp="2012-01-01T19:00:00" PrimaryLangID="en-us" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.opentravel.org/OTA/2003/05 ../Schemas/OTA_HotelResModifyRQ.xsd" Version="1">
    <POS>
        <Source ISOCountry="US" ISOCurrency="USD">
            <RequestorID Type="18" ID="7777777" />
        </Source>
    </POS>
    <HotelResModifies>
        <HotelResModify RoomStayReservation="true" CreateDateTime="2003-03-11T17:29:00-08:00" CreatorID="Expedia">
            <RoomStays>
                <RoomStay>
                    <RoomTypes>
                        <RoomType NumberOfUnits="1" />
                    </RoomTypes>
                    <RatePlans>
                        <RatePlan RatePlanCode="2222222" />
                    </RatePlans>
                    <GuestCounts>
                        <GuestCount AgeQualifyingCode="10" Count="1" />
                    </GuestCounts>
                    <TimeSpan Start="2012-08-15" End="2010-08-16" />
                    <Guarantee>
                        <GuaranteesAccepted>
                            <GuaranteeAccepted GuaranteeTypeCode="CC">
                                <PaymentCard CardCode="AX"
                                 ExpireDate="1215">
                                    <CardHolderName>CHRIS MILLER</CardHolderName>
                                    <Address>
                                        <AddressLine>18400 NE UNION HILL RD.</AddressLine>
                                        <CityName>REDMOND</CityName>
                                        <PostalCode>98052</PostalCode>
                                        <StateProv>WA</StateProv>
                                        <CountryName>US</CountryName>
                                    </Address>
                                </PaymentCard>
                            </GuaranteeAccepted>
                        </GuaranteesAccepted>
                    </Guarantee>
                    <BasicPropertyInfo HotelCode="HTL1111" />
                </RoomStay>
            </RoomStays>
            <ResGuests>
                <ResGuest ResGuestRPH="1" AgeQualifyingCode="10">
                    <Profiles>
                        <ProfileInfo>
                            <Profile>
                                <Customer>
                                    <PersonName>
                                        <GivenName>CHRIS</GivenName>
                                        <Surname>MILLER</Surname>
                                    </PersonName>
                                    <Telephone PhoneNumber="212-555-1212" />
                                    <Email>cmiller@example.com</Email>
                                    <Address>
                                        <AddressLine>18400 NE Union Hill Rd.</AddressLine>
                                        <CityName>Redmond</CityName>
                                        <PostalCode>98052</PostalCode>
                                        <StateProv>WA</StateProv>
                                        <CountryName>USA</CountryName>
                                    </Address>
                                </Customer>
                            </Profile>
                        </ProfileInfo>
                    </Profiles>
                </ResGuest>
            </ResGuests>
            <ResGlobalInfo>
                <HotelReservationIDs>
                    <HotelReservationID ResID_Value="888000888" />
                </HotelReservationIDs>
            </ResGlobalInfo>
        </HotelResModify>
    </HotelResModifies>
</OTA_HotelResModifyRQ>

Response

The supplier responds to the request by returning an updated booking identifier.

Content Types

application/xml

Response body

The response includes an OTA_HotelResModifyRS parent element with the following attributes:

The OTA_HotelResModifyRS parent element contains a Success element if the request was successful. It also contains a HotelResModifies element. The HotelResModifies element contains the HotelResModify element. The HotelResModify element contains the ResGlobalInfo child elements. The ResGlobalInfo element contains the HotelReservationIDs element. The HotelReservationIDs element contains two HotelReservationID child elements with the ResID_Value attribute containing the reservation ID. The first HotelReservationID element contains the original reservation identifier, and the second one contains the new reservation ID.

XML Example of Successful Response

HTTPS/1.1 200 OK
Content-Type: application/xml
Content-Length: {length of content body}

<?xml version="1.0" encoding="UTF-8" ?>
<OTA_HotelResModifyRS xmlns="http://www.opentravel.org/OTA/2003/05" EchoToken="ABC123" TimeStamp="2012-01-01T19:00:00" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.opentravel.org/OTA/2003/05 ../Schemas/OTA_HotelResModifyRS.xsd" Version="1">
    <Success />
    <HotelResModifies>
        <HotelResModify>
            <ResGlobalInfo>
                <HotelReservationIDs>
                    <HotelReservationID ResID_Value="888000888" />
                    <HotelReservationID ResID_Value="999000999" />
                </HotelReservationIDs>
            </ResGlobalInfo>
        </HotelResModify>
    </HotelResModifies>
</OTA_HotelResModifyRS>

List Item Web Service v1

This API has been deprecated.

Partners and customers using a deprecated API should contact SAP Concur and discuss moving to the latest versions.

Learn more in the API Lifecycle & Deprecation Policy.

Description

The Concur List Item web service provides an automated solution to clients who would like to add, update or delete list items. This web service solves several business problems:

Works With These Concur Products

Product Restrictions

Concur products are highly configurable, and not all clients will have access to all features.

Partner developers must determine which configurations are required for their solution prior to the review process.

Existing clients can work with Concur Advantage Technical Services to create custom applications that work with their configuration.

Resources

List

Responses and errors

List item errors

The web service will not return a 4xx HTTP response code for a batch operation even when every item in the batch failed to be created, updated or deleted. The client must inspect the response to look for warnings or errors with individual batch items.

When there are errors with batch items, the first ten errors are returned in the element in the request response, which includes their error code, the item that caused the error, and the error message. Any additional error messages are truncated. This prevents a large volume of error data in the event of a formatting mistake.

XML Response Error Codes

Error Code Message
1001 Could not find list-item-batch element
1002 Error parsing list item {ITEM}
1003 Start and end dates must be specified in pairs
1004 List item name must be specified
1005 List item name cannot be empty
1006 List item name exceeds 64 characters
1010 At least one level code must be specified
1011 Only one level code is allowed
1012 One or more level codes were skipped
1013 Invalid level1Code
1014 Invalid level2Code
1015 Invalid level3Code
1016 Invalid level4Code
1017 Invalid level5Code
1018 Invalid level6Code
1019 Invalid level7Code
1020 Invalid level8Code
1021 Invalid level9Code
1022 Invalid level10Code
1023 Invalid start date
1024 Invalid end date
1025 Start date must come before end date
2001 Failed to create list item
2002 Failed to update list item
2003 Failed to delete list item
2004 List item already exists in the database
2005 List item already exists as a deleted item in the database
2006 List item code error
2007 List item parent does not exist

Changing a List Item Level Code

The list item level code (levelxcode element) is the unique identifier for the list item. For multiple level lists, the combination of the level codes is the unique identifier. This value cannot be updated by a standard update request, as this will result in a new duplicate list value instead.
To change a list item's level code, the original list item must be deleted (using the Post List Item Deletion request), then the new item with the updated code must be added (using the Post New List Item request).

NOTE: When you delete a list item, the system deactivates it, but keeps a copy in case the item has been used in any expense reports, invoices or requests. Existing reports, invoices or requests will still show the old list item. Any reports, invoices or requests created after the list item has been deleted will no longer show it in the list.

See also

Posting Custom List Items

List Item Web Service v1 - List Resource

This API has been deprecated.

Partners and customers using a deprecated API should contact SAP Concur and discuss moving to the latest versions.

Learn more in the API Lifecycle & Deprecation Policy.

Description

The configured lists in Concur. Can be single or multiple level lists.

Works With These Concur Products

Version

1.0

URI

https://www.concursolutions.com/api/expense/list/v1.0/

Headers

Content-Type header

application/xml

Accept header

application/xml

Operations

List Item Web Service v1 - Get a list of lists

This API has been deprecated.

Partners and customers using a deprecated API should contact SAP Concur and discuss moving to the latest versions.

Learn more in the API Lifecycle & Deprecation Policy.

This resource supports the following GET actions:

Get Lists

Description

Retrieves the list of configured lists.

Get Lists Request

GET /api/expense/list/v1.0/ HTTPS/1.1
Host: www.concursolutions.com
Authorization: OAuth {access token}
Content-Type: application/xml

Request parameters

None.

Headers

Authorization header

Authorization header with OAuth token for valid Concur user. The OAuth consumer must have one of the following user roles in Concur: Company Administrator or Web Services Administrator for Professional, or Can Administer for Standard. These roles allow the user to manage data for the entire company.

Accept header

application/xml

Get Lists Response

HTTP Responses

Root elements

This request will return a lists parent element containing a list child element for each configured list. The list element will contain the following child elements.

list child elements
Element Description
id The list URI with encrypted ID.
items-link The list item URI with encrypted ID.
batch-link The batch URI associated with this list, with encrypted ID.
name The name of the list as it appears in the user interface.
is-vendor Whether this is a vendor list. Format: true/false
levels The number of levels the list contains.

XML Example of Successful Response

HTTPS/1.1 200 OK
Content-Type: application/xml
<lists xmlns="http://www.concursolutions.com/api/expense/list/2010/02">
    <list>
        <id>http://www.concursolutions.com/api/expense/list/v1.0/I8pq1l$rdSmdrEW23deOjPjyr4Wso0Wq$a</id>
        <batch-link>http://www.concursolutions.com/api/expense/list/v1.0/I8pq1l$rdSmdrEW23deOjPjyr4Wso0Wq$a/batch</batch-link>
        <name>Widget List</name>
        <is-vendor>false</is-vendor>
        <levels>1</levels>
        <items-link>http://www.concursolutions.com/api/expense/list/v1.0/I8pq1l$rdSmdrEW23deOjPjyr4Wso0Wq$a/items/</items-link>
    </list>
    <list>
        <id>http://www.concursolutions.com/api/expense/list/v1.0/jUwq11frTd$sweNd7s6s8O0fYi$piWwato</id>
        <batch-link>http://www.concursolutions.com/api/expense/list/v1.0/jUwq11frTd$sweNd7s6s8O0fYi$piWwato/batch</batch-link>
        <name>Organization List</name>
        <is-vendor>false</is-vendor>
        <levels>4</levels>
        <items-link>http://www.concursolutions.com/api/expense/list/v1.0/jUwq11frTd$sweNd7s6s8O0fYi$piWwato/items/</items-link>
    </list>
    <list>
        <id>http://www.concursolutions.com/api/expense/list/v1.0/4q2Hy86r45Klls$pseQEhNpz8Oxal7ytRe</id>
        <batch-link>http://www.concursolutions.com/api/expense/list/v1.0/4q2Hy86r45Klls$pseQEhNpz8Oxal7ytRe/batch</batch-link>
        <name>Airlines</name>
        <is-vendor>true</is-vendor>
        <levels>1</levels>
        <items-link>http://www.concursolutions.com/api/expense/list/v1.0/4q2Hy86r45Klls$pseQEhNpz8Oxal7ytRe/items/</items-link>
    </list>
</lists>

Get List Details

Description

Retrieves the list details for a specified list. Includes configuration information, not the list items.

Get List Details Request

GET /api/expense/list/v1.0/_{listID}_ HTTPS/1.1
Host: www.concursolutions.com
Authorization: OAuth {access token}
Content-Type: application/xml

Request parameters

Headers

Authorization header

Required. Authorization header with OAuth token for valid Concur user. The OAuth consumer must have one of the following user roles in Concur: Company Administrator or Web Services Administrator for Professional, or Can Administer for Standard. These roles allow the user to manage data for the entire company.

Accept header

application/xml

Get List Details Response

HTTP Responses

Content types

application/xml

Root elements

This request will return a list parent element. The list element will contain the following child elements.

list child elements

Element Description
batch-link The batch URI associated with this list, with encrypted ID.
id The list URI with encrypted ID.
is-vendor Whether this is a vendor list. Format: true/false.
items-link The list item URI with encrypted ID.
levels The number of levels the list contains.
name The name of the list as it appears in the user interface.

XML Example of Successful Response

<list xmlns="http://www.concursolutions.com/api/expense/list/2010/02" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
    <batch-link>https://www.concursolutions.com/api/expense/list/v1.0/nqd1YesaKhCWCFIhY8JeBJYf2UGdpwJ2r/batch</batch-link>
    <id>https://www.concursolutions.com/api/expense/list/v1.0/nqd1YesaKhCWCFIhY8JeBJYf2UGdpwJ2r</id>
    <is-vendor>true</is-vendor>
    <items-link>https://www.concursolutions.com/api/expense/list/v1.0/nqd1YesaKhCWCFIhY8JeBJYf2UGdpwJ2r/items</items-link>
    <levels>1</levels>
    <name>Travel Agents</name>
</list>

Get List Items

Description

Retrieves the list items for the specified list. A request sent without a specified parent list item code returns all level 1 list items. A request sent with a parent list item code returns all list items below that parent item. The result set can be filtered by passing in a filter string.

Get List Items Request

Request parameters

Headers

Authorization header

Required. Authorization header with OAuth token for valid Concur user. The OAuth consumer must have one of the following user roles in Concur: Company Administrator or Web Services Administrator for Professional, or Can Administer for Standard. These roles allow the user to manage data for the entire company.

Accept header

application/xml

XML Example Request

GET /api/expense/list/v1.0/jUwq11frTd$sweNd7s6s8O0fYi$piWwato/items/ HTTPS/1.1
Host: www.concursolutions.com
Authorization: OAuth {access token}
Content-Type: application/xml

XML Example Request with Parent Code

GET /api/expense/list/v1.0/jUwq11frTd$sweNd7s6s8O0fYi$piWwato/items?parentCode=US HTTPS/1.1
Host: www.concursolutions.com
Authorization: OAuth {access token}
Content-Type: application/xml

XML Example Request with Filter

GET /api/expense/list/v1.0/jUwq11frTd$sweNd7s6s8O0fYi$piWwato/items?filter=United HTTPS/1.1
Host: www.concursolutions.com
Authorization: OAuth {access token}
Content-Type: application/xml

Get List Items Response

HTTP Responses

Response body root elements

This request will return a list-items parent element, with a list-item child element for each item returned. The list-item elements will contain the following child elements.

list-item child elements
Element Description
name The list item name.
levelxcode The item code for all specified levels, where x is replaced with the level number. If the request is for the children of a level 2 item, the level1code, level2code, and level3code elements will be returned.
items-link The URI, including the parent code value, to request the list items beneath this list item.

XML Example of Successful Response

<list-items xmlns="http://www.concursolutions.com/api/expense/list/2010/02">
    <list-item>
        <name>United States</name>
        <level1code>US</level1code>
        <items-link>https://www.concursolutions.com/api/expense/list/v1.0/jUwq11frTd$sweNd7s6s8O0fYi$piWwato/items/US/</items-link>
    </list-item>
    <list-item>
        <name>United Kingdom</name>
        <level1code>UK</level1code>
        <items-link>https://www.concursolutions.com/api/expense/list/v1.0/jUwq11frTd$sweNd7s6s8O0fYi$piWwato/items/UK/</items-link>
    </list-item>
    <list-item>
        <name>Canada</name>
        <level1code>CA</level1code>
        <items-link>https://www.concursolutions.com/api/expense/list/v1.0/jUwq11frTd$sweNd7s6s8O0fYi$piWwato/items/CA/</items-link>
    </list-item>
    <list-item>
        <name>Mexico</name>
        <level1code>MX</level1code>
        <items-link>https://www.concursolutions.com/api/expense/list/v1.0/jUwq11frTd$sweNd7s6s8O0fYi$piWwato/items/MX/</items-link>
    </list-item>
</list-items>

Receipts v3 (Deprecated)

This API has been deprecated.

Deprecation Date: 02/07/2017 Unsupported Date: 08/07/2017 Decommissioned Date: 01/31/2021 Partners and customers using a deprecated API should contact SAP Concur and discuss moving to the latest versions.

Learn more in the API Lifecycle & Deprecation Policy.

Receipts v4 which replaces this API opens doors to global availability, enriched schemas, and better support for detailed tax content.

The Receipts resource represents receipts that can be posted to Concur by a provider company on behalf of opted-in users. This resource currently supports three types of receipts:

Notes:

Operations

Version

3.0

Create a new receipt

POST /api/v3.0/common/receipts

Parameters

Name Type Format Description
content - body The receipt object to create

Schema

Response

Name Type Format Description
ID string -
URI string -

Receipt

Name Type Format Description
Amount Decimal - Required The net amount of the transaction. A positive number means a payment is due. A negative number means a refund is due. Zero means no payment or refund is due. Range: -922,337,203,685,477 to 922,337,203,685,477
CurrencyCode string - Required The 3-letter ISO 4217 currency code for the currency paid to the provider.
CustomFields Array Custom Field The parent element for custom fields.
FormofPaymentCode string - Required The code for the form of payment. Possible values: CASH (Cash), CCARD (Credit Card), CPAID (Company Paid)
GeneralDetail GeneralDetail - The details of a general transaction. This element is required when the Type value is General.
HotelDetail HotelDetail - The details of a hospitality service. This element is required when the Type value is Hotel.
ImageBase64 string - The binary receipt image in Base64 encoding. This API supports PNG, JPEG, JPG, and PDF file formats.
MatchingFact MatchingFact - Required The parent element for information that is used to match the receipt to the Concur user who initiated the transaction. The MatchingFact object must contain either a valid access token or a Concur login ID.
Merchant Merchant - Required The parent element for information about the provider who is posting the receipt.
PaymentCard PaymentCard - The parent element for the credit card used for payment. This element is required when the FormofPaymentCode value is CCARD.
RideDetail RideDetail - The details of a hired ride. This element is required when the Type value is Ride.
TransactionDateTime DateTime - Required The date and time when the transaction happened (in Local Time). Format: YYYY-MM-DDThh:mm
Type string - Required The type of receipt. Possible values: General, Ride, Hotel

Custom Field

Name Type Format Description
Name string - Required The name of the custom field. Maximum length: 128 characters
Value string - Required The value of the custom field. Maximum length: 256 characters

General Detail

Name Type Format Description
LineItems Array Line Item The parent element for the line items in the receipt. There is a LineItem child element for each line item.

Line Item

Name Type Format Description
Amount Decimal - Required The total charged amount for the line item. Range: -922,337,203,685,477 to 922,337,203,685,477
Date DateTime - The date and time when the line item was charged (in Local Time). Format: YYYY-MM-DDThh:mm
Description string - Required The item's description. Maximum length: 100 characters
Description2 string - Additional details about the item. In the receipt image, the secondary description appears on the line following the primary description. Maximum length: 32 characters
Quantity Int32 - The quantity of units. Format: Any positive number
Rate Decimal - The amount charged per unit. Range: -922,337,203,685,477 to 922,337,203,685,477
RateType string - The unit of measure or rate type. Possible values: HOUR or PER HOUR, DAY or PER DAY, WEEK or PER WEEK, MONTH or PER MONTH. Maximum length: 10 characters
Reference string - The item's SKU, identifier, or some other attribute the provider uses to reference the item. Maximum length: 32 characters
SequenceNumber Int32 - Required The order in which the item appears in the sequence of line items.

Hotel Detail

Name Type Format Description
AverageDailyRoomRate Decimal - Required The sum of the room rate for each night stayed, divided by the number of nights stayed. Range: -922,337,203,685,477 to 922,337,203,685,477
CheckinDateTime DateTime - Required The check-in date and time (in Local Time). Format: YYYY-MM-DDThh:mm
CheckoutDateTime DateTime - Required The check-out date and time (in Local Time). Format: YYYY-MM-DDThh:mm
ConfirmationNumber string - The confirmation number for the booking. Maximum length: 32 characters
GNR string - The Guest Name Record (GNR) for the stay. Maximum length: 20 characters
LineItems Array Line Item The parent element for the line items in the receipt. There is a LineItem child element for each line item.
NumberInParty Int32 - The number of people for this stay.
RatePlanType string - The rate plan type that is used to calculate the room rate. Possible values are rate plan types defined using hospitality industry standards. Maximum length: 50 characters
RoomNumber string - The room number for the stay. Maximum length: 15 characters
RoomType string - The type of room. Possible values are room types defined using hospitality industry standards, such as Single, Double, Suite, and so on. Maximum length: 50 characters

Matching Fact

Name Type Format Description
Type string - Required The type of matching fact that is used to identify the Concur user who owns the receipt. Possible values: OAuth, Login
Value string - Required The value of the matching fact. If the Type element is set to OAuth, this value must be the access token for the Concur user who owns the receipt. In this case, the access token must not be expired or revoked. If the Type element is set to Login, this value must be the login ID of the Concur user who owns the receipt.

Merchant

Name Type Format Description
Location Location - Required The parent element for the provider location.
Name string - Required The name of the provider (Merchant). Maximum length: 64 characters

Location

Name Type Format Description
Address string - The provider's street address. Maximum length: 100 characters
Address2 string - The provider's secondary street address. Maximum length: 50 characters
City string - The provider's city. Maximum length: 100 characters
CountryCode string - Required The provider's country. Format: 2-letter ISO 3166-1 country code
CountrySubdivisionCode string - The provider's state, province, or other country subdivision. Format: ISO 3166-2:2007 country subdivision code YYY, where YYY is the one-to-threeÐcharacter subdivision code
EmailAddress string - The provider's email address. Maximum length: 255 characters
FaxNumber string - The provider's fax number. Maximum length: 32 characters
InternetAddress string - The provider's Web address. Maximum length: 255 characters
Name string - The name of the provider's location, such as an airport, car rental agency, property, store, or other named location. Maximum length: 100 characters
PostalCode string - The provider's postal code. Maximum length: 20 characters
TelephoneNumber string - The provider's telephone number. Maximum length: 100 characters

Payment Card

Name Type Format Description
AuthorizationCode string - The authorization code that the card interchange provided when it approved this purchase. Maximum length: 15 characters
MaskedNumber string - Required The masked card number for the credit card. With the exception of the AX (American Express) card type, this is the last four digits of the card number. For American Express, the value can be one of these, in order of preference: a) The first six digits and the last four digits of the card number. b) The last five digits. c) The last four digits.
type string - Required The card interchange for the credit card. Possible values: AX (American Express), DC (Diner's Club), DS (Discover), CA (MasterCard), VI (Visa), CB (Carte Blanche), ER (Enroute), TP (Universal Air Travel), JC (JCB), EC (EuroCard), OTHER (other types)

Ride Detail

Name Type Format Description
DriverName string - The name of the driver. Maximum length: 255 characters
DropoffLatitude Decimal - The latitude of the ride end location. Range: -90 to 90
DropoffLongitude Decimal - The longitude of the ride end location. Range: -180 to 180
EndDateTime DateTime - Required The ending date and time for the ride (in Local Time). Format: YYYY-MM-DDThh:mm
LineItems Array Line Item The parent element for the line items in the receipt. There is a LineItem child element for each line item.
StartDateTime DateTime - Required The starting date and time for the ride (in Local Time). Format: YYYY-MM-DDThh:mm
VehicleNumber string - The unique identifier for the vehicle. Maximum length: 50 characters

Request URL

https://www.concursolutions.com/api/v3.0/common/receipts

JSON example of a successful response

{
  "ID": "270583561310",
  "URI": ""
}

Request v3

This API has been deprecated.

Partners and customers using a deprecated API should contact SAP Concur and discuss moving to the latest versions.

Learn more in the API Lifecycle & Deprecation Policy.

Concur Request automates the spend request and approval process for both travel and everyday expenses, giving you the data you need to accurately track and better control spending. By increasing visibility into planned expenses and up-to-date budget data, you can make strategic spending decisions before any spending actually occurs. The Request resource provides many abilities, including viewing requests and transition of requests into the workflow.

Versions

Retrieve all requests

GET /api/v3.0/travelrequest/requests

Parameters

Name Type Format Description
offset string query Starting page offset
limit Int32 query Number of records to return (default 100)
user string query The login ID of the user who owns this Request. The user must have the Web Services Admin (Professional) or Can Administer (Standard) user role to use this parameter.
status string query The Status search term specifies which travel request or approval status to return. If no Status value is sent, the default Status of Active will be used.
modifiedAfter DateTime query This returns travel requests in which the associated dependents (header, entries, segments, allocations, attendees, comments) were modified after the specified date and time. This search term can be used along with other search terms to narrow the results. The date and time (if desired) should be in UTC. The format is: YYYY-MM-DDThh:mm:ss.
modifiedBefore DateTime query This returns travel requests in which the associated dependents (header, entries, segments, allocations, attendees, comments) were modified before the specified date and time. This search term can be used along with other search terms to narrow the results. The date and time (if desired) should be in UTC. The format is: YYYY-MM-DDThh:mm:ss.
withSegmentTypes Boolean query Pass true to populate the SegmentType field in the result.

Retrieve a request by ID

GET /api/v3.0/travelrequest/requests/{id}

Parameters

Name Type Format Description
id string path Required The Request ID
user string query The login ID of the user. Optional. The user must have the Web Services Admin (Professional) or Can Administer (Standard) user role to use this parameter.

Submit a request by ID

POST /api/v3.0/travelrequest/requests/{id}/submit

Parameters

Name Type Format Description
id string path The Request ID

Schema

Request

Name Type Format Description
AgencyOfficeName string - The travel agency office name.
AllocationFormID string - The unique identifier of the Segment Form resource (See the "Forms" resource for more information).
ApprovalLimitDate DateTime - The date by which the Request must be approved. This element appears only when integrated with Concur Travel.
ApprovalStatusCode string - The code for the approval status the Request.
ApprovalStatusName string - The approval status of the Request.
AuthorizedDate DateTime - The date the Request was authorized. Format: YYYY-MM-DDThh:mm:ss.
CashAdvances Array Cash Advance This parent element has a CashAdvance child element for each cash advance. See the CashAdvance model for the full list of child elements.
Comments Array Comment This parent element has a Comment child element for each comment. See the Comment model for the full list of child elements.
CreationDate DateTime - The date of the Request was created.
CurrencyCode string - The 3-letter ISO 4217 currency code for the Request currency. The Request currency is defined as the Request creator's default reimbursement currency.
CurrencyName string - The currency name for the Request currency. The Request currency is defined as the Request creator's default reimbursement currency.
Custom1 through Custom20 CustomField - The details from the Custom fields. These fields may not have data, depending on the configuration.
EmployeeName string - The first, middle (or middle initial), and last name of the employee who created the Request.
EndDate string - The end date of the Request.
EndTime string - The end time for the Request.
Entries Array Entry This parent element has a RequestEntry child element for each entry. See the RequestEntry model for the full list of child elements.
EverSentBack string - Indicates whether the Request has ever been sent back to the employee. Format: Y/N
Exceptions Array Exception This parent element has an Exception child element for each exception. See the Exception model for the full list of child elements.
ExtensionOf string - The ID of the initial Request that this Request is an extension of or adendum to.
HasException string - Indicates whether the Request has exceptions. Format: Y/N
HeaderFormID string - The unique identifier of the Header Form resource (See the "Forms" resource for more information).
LastModifiedDate DateTime - The date the Request was last modified. Format: YYYY-MM-DDThh:mm:ss
LoginID string - The Concur login ID of the Request owner.
Name string - The name of the Request.
PolicyID string - The unique identifier of the policy that applies to this Request. Maximum length 64 characters.
PolicyName string - The name of the policy that applies to this Request.
Purpose string - The purpose of the Request.
RequestID string - The unique key for the Request.
StartDate string - The start date of the Request.
StartTime string - The start time for the Request.
SubmitDate DateTime - The date the Request was submitted. Format: YYYY-MM-DDThh:mm:ss.
TotalApprovedAmount string - The total amount of approved expenses in the Request.
TotalPostedAmount string - The total amount of the Request.
TotalRemainingAmount string - The total amount of expenses remaining in the Request.
UserPermissions UserPermissions - The actions that the user is allowed to perform on the Request.

Cash Advance

Name Type Format Description
AmountRequested string - The amount requested in the cash advance, in the currency specified in the CurrencyCode element.
ApprovalStatusName string - The approval status of the cash advance.
Comments Array Comment This parent element has a Comment child element for each comment. Refer to the Comments model for the full list of child elements.
CurrencyCode string - The 3-letter ISO 4217 currency code for the cash advance currency.
CurrencyName string - The name of the currency for the cash advance.
EmployeeCurrencyCode string - The 3-letter ISO 4217 currency code for the employee's currency, also known as the home currency.
EmployeeCurrencyName string - The name of the employee's currency, also known as the home currency.
ExchangeRate string - The exchange rate that applies to the cash advance.
IssueDate DateTime - The issue date for the cash advance.
RequestDate DateTime - The date of cash advance request, obtained from the detailed cash advance record.
StartingBalance string - The initial balance for the cash advance.

Comment

Name Type Format Description
AuthorFirstName string - The first name of the person who made the comment.
AuthorLastName string - The last name of the person who made the comment.
CommentDateTime DateTime - The time, in GMT, when the user made the comment.
IsLatest bool - Indicates that the comment is the last one.
Value string - The text of the Request header comment.

Custom

Name Type Format Description
Code string - For list fields, this is the list item code.
ListItemID string - For list fields, this is the list item ID.
Type string - The custom field type. Possible values: Amount, Boolean, ConnectedList, Date, Integer, List, Number, Text
Value string - The value in the Org Unit or Custom field. For list fields, this is the name of the list item. Maximum length: 48 characters

Entry

Name Type Format Description
Allocations Array Allocation This parent element has an Allocation child element for each associated allocation. See the Allocation model for the full list of child elements.
ApprovedAmount string - The approved amount of the Request entry in the Request currency.
Comments Array Comment This parent element has a Comment child element for each comment. See the Comments model for the full list of child elements.
Custom1 through Custom40 CustomField - The details from the Custom fields. These fields may not have data, depending on the configuration.
EntryDescription string - The description of the Request entry.
EntryFormID string - The unique identifier of the Entry Form resource (See the "Forms" resource for more information).
Exceptions Array Exception This parent element has an Exception child element for each exception. See the Exception model for the full list of child elements.
ExchangeRate string - The exchange rate that applies to the entry.
ExpenseTypeName string - The expense type name.
ForeignAmount string - The foreign amount of the Request entry.
ForeignCurrencyCode string - The 3-letter ISO 4217 currency code for the foreign currency amount of the Request entry.
ForeignCurrencyName string - The name of the currency for the foreign amount.
LastModifiedDate DateTime - The date the entry was last modified. Format: YYYY-MM-DDThh:mm:ss
OrgUnit1 through OrgUnit6 CustomField - The details from the Org Unit custom fields. These fields may not have data, depending on the configuration.
PostedAmount string - The posted amount of the Request entry in the Request currency.
RemainingAmount string - The remaining amount of the Request entry in the Request currency.
Segments Array Segment This parent element has a Segment child element for each segment associated with the travel request. See the Segment model for the full list of child elements.
TransactionDate DateTime - The date of the Request entry.
TripType string - ['ONE_WAY' or 'ROUND_TRIP' or 'MULTI_STOP'] Trip type of the air or rail segment. Possible values are: ONE_WAY, ROUND_TRIP and MULTI_STOP.

Allocation

Name Type Format Description
Custom1 through Custom20 CustomField - The details from the Custom fields. These fields may not have data, depending on the configuration.
Percentage string - The percentage of the expense that is included in this allocation.

Exception

Name Type Format Description
Code string - The system exception code defined for the exception. Example: BADCODE
Level int - The numeric level associated with the exception. Example: 99
Message string - The user-facing message defined for the exception.

Segment

Name Type Format Description
ApprovedAmount string - The approved amount of the segment in the Request currency.
ArrivalDate string - The arrival date of the segment.
ArrivalTime string - The arrival time of the segment.
ClassOfServiceCode string - The Class of Service Code from Concur Travel. Appears only when the Request is integrated with Concur Travel.
Comments Array Comment The list of comments added for this segment.
Custom1 through Custom40 CustomField - The details from the Custom fields. These fields may not have data, depending on the configuration.
DepartureDate string - The departure date of the segment.
DepartureTime string - The departure time of the segment.
Exceptions Array Exception This parent element has an Exception child element for each exception. Refer to the Exception model for the full list of child elements.
ExchangeRate string - The exchange rate that applies to the segment.
FlightNumber string - The flight number for air segments. Appears only when Request is integrated with Concur Travel.
ForeignAmount string - The foreign currency amount of the segment.
ForeignCurrencyCode string - The 3-letter ISO 4217 currency code for the foreign currency amount of the segment.
ForeignCurrencyName string - The name of the currency for the foreign amount of the segment.
FormTypeCode string - The code for form type of the segment type.
FromLocationDetail string - The code for the starting location.
FromLocationID string - The unique identifier of the departure location. (See the "Locations" resource for more information).
FromLocationName string - The name of the starting location.
IsAgencyBooked string - Indicates whether the air segment was agency booked. Format: Y/N.
IsSelfBooked string - Indicates whether the air segment was self booked. Format: Y/N.
LastModifiedDate DateTime - The date the segment was last modified. Format: YYYY-MM-DDThh:mm:ss
OutboundSegmentID string - REQ_SEGMENT_OUTBOUND_ID
PostedAmount string - The posted amount of the segment in the Request currency.
RecordLocator string - Appears only when the Request is integrated with Concur Travel.
RemainingAmount string - The remaining amount of the segment in the Request currency.
SegmentFormID string - The unique identifier of the Segment Form resource (See the "Forms" resource for more information).
SegmentLocator string - The unique identifier for the Concur Travel segment associated with this segment. Appears only when the Request is integrated with Concur Travel.
SegmentType string - The type of itinerary segment. Format: air, car, hotel, rail, dining, event, ground, taxi, parking, other and so on
SegmentTypeCode string - The code for the type of itinerary segment.
ToLocationDetail string - The code for the ending location.
ToLocationID string - The unique identifier of the arrival location. (See the "Locations" resource for more information).
ToLocationName string - The name of the ending location.
TripLocator string - The unique identifier for the Concur Travel trip associated with this segment. Appears only when the Request is integrated with Concur Travel.

User Permissions

Name Type Format Description
Links Array Link The actions that the user is allowed to perform on the Request.
Name Type Format Description
Action string - The action that the user is allowed to perform on the resource.
Method string - The method of the request. Possible values: GET, POST, PUT and DELETE.
Url string - The URL of the resource that the user can access.

Travel Profile v1 - User Notification

This API has been deprecated.

Partners and customers using a deprecated API should contact SAP Concur and discuss moving to the latest versions.

Learn more in the API Lifecycle & Deprecation Policy.

A subscription to a notification when the SAP Concur user changes the specified features of their SAP Concur account or data. Currently supports notifications for the following events: Itinerary change (create or update), Travel Profile basic information change, or Travel Profile Form of Payment change. This functionality is restricted to Travel Suppliers or TMCs (Travel Management Companies) who have registered with SAP Concur.

NOTE: This resource can only be accessed by partner applications that have selected the User API scope.

Resource URI

To subscribe:

https://www.concursolutions.com/api/user/v1.0/subscribe

To unsubscribe:

https://www.concursolutions.com/api/user/v1.0/unsubscribe

Headers

Content-Type Header

application/xml

Accept Header

application/xml

Operations

Subscribe to Notifications for Itinerary Changes

Subscribes or unsubscribes the travel supplier from notifications when the user adds, modifies, or cancels an itinerary. This functionality is only available to travel suppliers that have an application on the App Center tab of SAP Concur. The supplier must also have received authorization by the user to access their trip information.

Request

To subscribe:

shells://www.concursolutions.com/api/travelprofile/v1.0/subscribe?type=itinerary

To unsubscribe:

https://www.concursolutions.com/api/travelprofile/v1.0/unsubscribe?type=itinerary

Request Parameters

Name Description
type=itinerary The type of subscription. Required.

Headers

Authorization Header

Required. Authorization header with OAuth token for the desired SAP Concur user. This token is granted as part of the OAuth 2.0 Web flow authorization process.

Example: Subscribe to Itinerary Changes

POST https://www.concursolutions.com/api/travelprofile/v1.0/subscribe?type=itinerary HTTP/1.1
Authorization: OAuth {access token}

Post Notification Subscription for Itinerary Changes Response

Notification Format

The notification will be sent to the Postback URL that the supplier has registered with SAP Concur during application review. Suppliers can only have one postback URL for all notification types. The notification will include the type and oauth_token_key query parameters, specifying the OAuth information for the updated user:

https://postbackurl.com?type=Itinerary&oauth_token_key={oauth_token}

Response Body Schema

The request will include a Notification parent element, with the following child elements:

Element Description
ObjectType ITINERARY
ObjectURI The URI for the object. The developer can use the appropriate GET endpoint with the ObjectURI to get complete details for the trip. For Itinerary, the ObjectURI value is the same as the TripId value.
EventDateTime When the event happened. Format: YYYY-MM-DDThh:mm:ss
EventType The type of the change. Format: CREATE, UPDATE, CANCEL
Context This is not used yet but will be used in the future to specify the change in the trip. Developers can use this in conjunction with EventType to decide how to process the notification.
TripId The unique identifier for the trip. Format: String

Example: Post a of Notification in XML Format

POST https://www.postbackurl.com?type=itinerary&oauth_token_key={oauthtoken} HTTP/1.1
Authorization: OAuth {access token}
Content-Type: application/xml
<?xml version="1.0" encoding="utf-8"?>
<Notification>
  <ObjectType>ITINERARY</ObjectType>
  <ObjectURI>https://www.concursolutions.com/api/travel/trip/v1.1/naIzQJ0y2DBWjCIQOb2SHTsozwBsHDkdP</ObjectURI>
  <EventDateTime>2013-02-13T08:12:35</EventDateTime>
  <EventType>CREATE</EventType>
  <Context/>
  <TripId>naIzQJ0y2DBWjCIQOb2SHTsozwBsHDkdP</TripId>
</Notification>

XML Example of Successful Response for Itinerary Changes

200 OK

Subscribe for Notifications for Payment Changes

Description

Subscribes or unsubscribes the travel supplier from notifications when the user's Form of Payment information changes. This functionality is only available to travel suppliers that have an application on the App Center tab of SAP Concur. The supplier must also have received authorization by the user to access their Form of Payment information.

NOTE: SAP Concur will send a notification when any area of the user's Form of Payment is updated. This may include fields that are not available through the Travel Profile web service.

Post Notification Subscription for Form of Payment Changes Request

Request Parameters

Name Description
type=fop The type of subscription. Required.

Examples

To subscribe:

https://www.concursolutions.com/api/travelprofile/v1.0/subscribe?type=fop

To unsubscribe:

https://www.concursolutions.com/api/travelprofile/v1.0/unsubscribe?type=fop

Headers

Authorization Header

Required. Authorization header with OAuth token for the desired SAP Concur user. This token is granted as part of the OAuth 2.0 Web flow authorization process.

XML Example Request

POST https://www.concursolutions.com/api/travelprofile/v1.0/subscribe?type=fop HTTP/1.1
Authorization: OAuth {access token}

Post Notification Subscription for Form of Payment Changes Response

Notification Format

The notification will be sent to the Postback URL that the supplier has registered with SAP Concur during application review. Suppliers can only have one postback URL for all notification types. The notification will include the type and oauth_token_key query parameters, specifying the OAuth information for the updated user:

https://postbackurl.com?type=FOP&oauth_token_key={oauth_token}

XML Example of Successful Response

200 OK

Subscribe for Notifications for Travel Profile Changes

Subscribes or unsubscribes the travel supplier from notifications when the user's Travel Profile information changes. This functionality is only available to travel suppliers that have an application on the App Center tab of SAP Concur. The supplier must also have received authorization by the user to access their travel profile information.

NOTE: SAP Concur will send a notification when any area of the user's Travel Profile is updated. This may include fields that are not available through the Travel Profile web service.

Request

Request parameters

Name Description
type=profile The type of subscription. Required.

Examples

To subscribe:

https://www.concursolutions.com/api/travelprofile/v1.0/subscribe?type=profile

To unsubscribe:

https://www.concursolutions.com/api/travelprofile/v1.0/unsubscribe?type=profile

Headers

Authorization header

Required. Authorization header with OAuth token for the desired SAP Concur user. This token is granted as part of the OAuth 2.0 Web flow authorization process.

Request

POST https://www.concursolutions.com/api/travelprofile/v1.0/subscribe?type=profile HTTP/1.1
Authorization: OAuth {access token}

Response

Notification Format

The notification will be sent to the Postback URL that the supplier has registered with SAP Concur during application review. Suppliers can only have one postback URL for all notification types. The notification will include the type and oauth_token_key query parameters, specifying the OAuth information for the updated user:

https://postbackurl.com?type=Profile&oauth_token_key={oauth_token}

XML Example of Successful Response

200 OK

Travel Profile v1 - Company Notification

This API has been deprecated.

Partners and customers using a deprecated API should contact SAP Concur and discuss moving to the latest versions.

Learn more in the API Lifecycle & Deprecation Policy.

A subscription to a notification when any user in the SAP Concur company changes the specified features of their SAP Concur account or data. Currently supports notifications for the following events: Itinerary change (create or update), Travel Profile basic information change.

This functionality requires that the partner complete the OAuth process with an administrative user from the SAP Concur company. This resource can only be accessed by partner applications that have selected the User API scope.

URI

To subscribe:

https://www.concursolutions.com/api/company/v1.0/subscribe

To unsubscribe:

https://www.concursolutions.com/api/company/v1.0/unsubscribe

Content Type

application/xml

Operations

Post Company Notification Subscription for Itinerary Changes

Description

Subscribes or unsubscribes the partner from notifications when any users in the company add, modify, or cancel an itinerary. The partner must have received authorization using OAuth by an administrative user at the company to access the company's trip information.

Post Company Notification Subscription for Itinerary Changes Request

Headers

Request Parameters

Name Description
type=itinerary Required. The type of subscription.

Examples

To subscribe: https://www.concursolutions.com/api/company/v1.0/subscribe?type=itinerary

To unsubscribe:

https://www.concursolutions.com/api/company/v1.0/unsubscribe?type=itinerary

Authorization Header

Required. Authorization header with OAuth token for an administrative user at the company. The user must have one of the following user roles in SAP Concur: Company Administrator or Web Services Administrator for Professional, or Can Administer for Standard.

XML Example Request

POST http://www.concursolutions.com/api/company/v1.0/subscribe?type=itinerary HTTP/1.1
Authorization: OAuth {access token}

Post Company Notification Subscription for Itinerary Changes Response

Notification Format

The notification will be sent to the Postback URL that the partner has registered with SAP Concur during application review. Partners can only have one Postback URL for all notification types. The notification will include the type, oauth_token_key, userid_type, and userid_value query parameters, specifying the updated user:

https://postbackurl.com?type=itinerary&oauth_token_key={oauthtoken}&userid_type=login&userid_value=cm@example.com

Company Notification Subscription for Itinerary Changes Response Schema

The response body will include a Notification parent element, with the following child elements.

Element Description
ObjectType ITINERARY
ObjectURI The URI for the object. The developer can use the appropriate GET endpoint with the ObjectURI to get complete details for the trip.
EventDateTime When the event happened. Format: YYYY-MM-DDThh:mm:ss
EventType The type of the change. Format: CREATE, UPDATE, CANCEL
Context This is not used yet but will be used in the future to specify the change in the trip. Developers can use this in conjunction with EventType to decide how to process the notification.
TripId The unique identifier for the trip. Format: String

XML Example of Successful Response

200 OK

XML Example of Notification

POST https://www.postbackurl.com?type=itinerary&oauth_token_key={oauthtoken}&userid_type=login&userid_value=cm@example.com HTTP/1.1
Content-Type: application/xml
<?xml version="1.0" encoding="utf-8"?>
<Notification>
  <ObjectType>ITINERARY</ObjectType>
  <ObjectURI>https://www.concursolutions.com/api/travel/trip/v1.1/naIzQJ0y2DBWjCIQOb2SHTsozwBsHDkdP</ObjectURI>
  <EventDateTime>2013-02-13T08:12:35</EventDateTime>
  <EventType>CREATE</EventType>
  <Context/>
  <TripId>naIzQJ0y2DBWjCIQOb2SHTsozwBsHDkdP</TripId>
</Notification>

Post Company Notification Subscription for Payment Changes

Description

Subscribes or unsubscribes the partner from notifications when the company's Payment information changes. The partner must have received authorization using OAuth by an administrative user at the company to access the company's form of payment information.

Post Company Notification Subscription for Payment Changes Request

Headers

Request Parameters

Name Description
type=fop The type of subscription. Required.

Examples

To subscribe:

https://www.concursolutions.com/api/company/v1.0/subscribe?type=fop

To unsubscribe:

https://www.concursolutions.com/api/company/v1.0/unsubscribe?type=fop

Headers

Authorization Header

Required. Authorization header with OAuth token for the desired SAP Concur user. This token is granted as part of the OAuth 2.0 Web flow authorization process.

XML Example Request

POST https://www.concursolutions.com/api/company/v1.0/subscribe?type=fop HTTP/1.1
Authorization: OAuth {access token}

Post Notification Subscription for Form of Payment Changes Response

Notification Format

The notification will be sent to the Postback URL that the supplier has registered with Concur during application review. Suppliers can only have one Postback URL for all notification types. The notification will include the type and oauth_token_key query parameters, specifying the OAuth information for the updated user:

https://postbackurl.com?type=FOP&oauth_token_key={oauth_token}

XML Example of Successful Response

200 OK

Post Company Notification Subscription for Travel Profile Changes

Description

Subscribes or unsubscribes the partner from notifications when the company's Travel Profile information changes. The partner must have received authorization using OAuth by an administrative user at the company to access the company's trip information.

NOTE: Concur will send a notification when any area of the user's Travel Profile is updated. This may include fields that are not available through the Travel Profile web service.

Post Company Notification Subscription for Travel Profile Changes Request

Headers

Request Parameters
Name Description
type=profile Required. The type of subscription.

Examples

To subscribe:

https://www.concursolutions.com/api/company/v1.0/subscribe?type=profile

To unsubscribe:

https://www.concursolutions.com/api/company/v1.0/unsubscribe?type=profile
Authorization Header

Required. Authorization header with OAuth token for an administrative user at the company. The user must have one of the following user roles in SAP Concur: Company Administrator or Web Services Administrator for Professional, or Can Administer for Standard.

XML Example Request

POST <https://www.concursolutions.com/api/company/v1.0/subscribe?type=profile> HTTP/1.1
Authorization: OAuth {access token}

Post Company Notification Subscription for Travel Profile Changes Response

Notification Format

The notification will be sent to the Postback URL that the partner has registered with SAP Concur during application review. Partners can only have one Postback URL for all notification types. The notification will include the type, oauth_token_key, userid_type, and userid_value query parameters, specifying the updated user:

https://postbackurl.com?type=profile&oauth_token_key={oauthtoken}&userid_type=login&userid_value=cm@example.com

The partner can use this information to make a Get Travel Profile request.

XML Example of Successful Response

200 OK

Profile v1 - User

This API has been deprecated.

Partners and customers using a deprecated API should contact SAP Concur and discuss moving to the latest versions.

Learn more in the API Lifecycle & Deprecation Policy.

Getting Started - Company API - User API

The Concur's user API is used to help provision and manage user accounts and profile details across multiple Concur products, including Expense, Invoice, Request, Travel and TripIt.

Version

1.0

Profile v1 User - Definition

The User schema is inspired by the work from System for Cross-domain Identity Management (SCIM), in particular:

The latest version of the User schema is always available at: user.json.

Get User

Profile supports user information retrieval with access tokens. And the access token will limit the user account, as well as the user attributes, that you can query for. You can use the following endpoint to lookup your user:

GET /profile/v1/me
(access token required)

Curl example:

curl -k -v -H "Authorization: Bearer $access-token" "https://$host/profile/v1/me"

The above calls will retrieve general user profile information. User resource also supports a schema parameter to limit or expand the data returned. To limit the amount of data returned, you can use ?schema=compact. To also retrieve expense related data, you can use ?schema=expense. You can also provide comma delimited schema list for the parameter, such as ?schema=compact,expense.

User details

Here is a sample user response, without compact, but with expense schema.

{
  "active": true,
  "id": "1c1e5ec5-1abc-4edd-a92a-bc551d0dfcd7",
  "userType": "Enterprise",
  "meta": {
    "created": "2017-03-30T00:00:00.000",
    "lastModified": "2017-07-03T17:46:00.000",
    "principalType": "user",
    "resourceType": "EnterpriseUser"
  },
  "preferredLanguage": "en",
  "dateOfBirth": "1990-01-01",
  "schemas": [
    "com:concur:User:1.0",
    "com:concur:Employee:1.0",
    "com:concur:TravelPreferences:1.0",
    "com:concur:Programs:1.0",
    "com:concur:Documents:1.0",
    "com:concur:Expense:0.2"
  ],
  "gender": "Male",
  "emails": [
    {
      "value": "1@profile-58dd7cd7.com",
      "type": "Business",
      "notifications": true,
      "verified": false
    },
    {
      "value": "test.user@concur.com",
      "type": "Personal",
      "notifications": true,
      "verified": false
    }
  ],
  "com:concur:Documents:1.0": {
    "passport": [
      {
        "number": "12345678",
        "issuingCountry": "US",
        "placeIssued": "Bellevue",
        "dateIssued": "2017-06-02",
        "expiration": "2023-06-30"
      }
    ],
    "visa": [
      {
        "number": "987654321",
        "issuedByCountry": "AF",
        "placeIssued": null,
        "issuedForCountry": null,
        "dateIssued": null,
        "expiration": "2021-06-03"
      }
    ]
  },
  "addresses": [
    {
      "type": "Home",
      "streetAddress": "profile-58dd7cd7 home address",
      "locality": "Redmond",
      "region": "WA",
      "postalCode": "98052",
      "country": "US"
    },
    {
      "type": "Work",
      "streetAddress": "profile-58dd7cd7 office",
      "locality": "bellevue",
      "region": "WA",
      "postalCode": "98004",
      "country": "US"
    }
  ],
  "com:concur:Employee:1.0": {
    "companyUUID": "d63d3d33-9255-41f4-8a1c-dabd6ab08578",
    "companyInternalId": 277471,
    "employeeId": "1@profile-58dd7cd7.com",
    "jobTitle": "",
    "managerId": "ae3204d3-a94f-47ad-94ef-8234ac40e560",
    "orgUnitId": 80265
  },
  "com:concur:TravelPreferences:1.0": {
    "air": {
      "seat": {
        "interrowPosition": "Aisle",
        "sectionPosition": "Forward"
      },
      "homeAirport": "SEA",
      "meal": "BLML"
    },
    "rail": {
      "space": "DontCare",
      "meal": "DontCare",
      "bedCategory": "DontCare",
      "fareSpaceComfort": "DontCare",
      "deck": "DontCare",
      "coach": "DontCare",
      "bed": "DontCare",
      "berth": "DontCare",
      "noiseComfort": "DontCare",
      "contingency": "DontCare",
      "seat": "DontCare"
    },
    "car": {
      "smoking": "NonSmoking",
      "carType": "Mini",
      "transmission": "Automatic",
      "gpsEnabled": false,
      "skirack": false
    },
    "hotel": {
      "earlyCheckin": true,
      "remark": null,
      "pool": true,
      "roomService": true,
      "foamPillows": true,
      "accessForBlind": true,
      "accessForWheelchair": true,
      "gym": true,
      "roomType": "King",
      "restaurant": true,
      "rollawayBed": true,
      "smoking": "NonSmoking",
      "crib": true
    }
  },
  "com:concur:Programs:1.0": {
    "rail": [
      {
        "default": false,
        "pointsNext": null,
        "expiration": null,
        "nextStatus": null,
        "points": null,
        "segments": null,
        "parentChainVendorName": null,
        "vendorName": "AccesRail",
        "account": "123454321",
        "statusBenefits": null,
        "status": null,
        "segmentsNext": null,
        "parentChainVendorCode": null,
        "vendorCode": "9B"
      }
    ],
    "air": [],
    "hotel": [],
    "car": []
  },
  "com:concur:Expense:0.2": {
    "middleInitial": "T",
    "middleName": "Test",
    "loginId": "1@profile-58dd7cd7.com",
    "ledger": "DEFAULT",
    "countrySubdivision": null,
    "driverId": null,
    "cuuid": "8002699190004701412",
    "cashAdvanceAccountCode": null,
    "emailAddress": "1@profile-58dd7cd7.com",
    "employeeId": "1@profile-58dd7cd7.com",
    "firstName": "Concur",
    "reimbursementType": "APCHECK",
    "reimbursementCurrency": "USD",
    "active": true,
    "lastName": "User",
    "uuId": "1c1e5ec5-1abc-4edd-a92a-bc551d0dfcd7",
    "orgUnitData": [
      {
        "orgUnitName": "Expense Policy Group",
        "orgUnitValue": null
      }
    ],
    "customData": [
      {
        "customFieldName": "Invoice Policy Group",
        "customFieldValue": null
      },
      {
        "customFieldName": "Employee Administration Country",
        "customFieldValue": "United States"
      }
    ],
    "localeCode": "en_US",
    "countryCode": "US"
  }
}

HTTP Status Codes

HTTP Status Status Description/Error Code
200 Success Resource retrieved or updated
201 Success Resource created
204 Success Operation exectuted successfully, with no content returned
301 Moved Permanently Resource is at a different location
400 Bad Request -
401 Unauthorized -
403 Forbidden -
404 Resource not found -
429 Rate limit reached -
500 Internal Error -
503 Service Unavailable -

Profile v1 - Getting Started

This API has been deprecated.

Partners and customers using a deprecated API should contact SAP Concur and discuss moving to the latest versions.

Learn more in the API Lifecycle & Deprecation Policy.

Getting Started - Company API - User API

The Concur's Profile API consists of a set of APIs to manage users, companies and apps within Concur. Profile API is the API for profile information for all Concur's profile data, including Enterprise applications such as Expense, Invoice, Request, and Travel, as well as Retail applications such as Hipmunk and TripIt.

Security

Profile API can be accessed using following authentication methods:

Access Token Authentication

An access token based authenticated call is made in the context of a principal (user/company/app). When an access token is used, it must be supplied in the 'Authorization' HTTP header by the caller.

The access token must have scopes that are relevant for the API call. For example, in order to call the Company API correctly, the token must include the company.read scope or the API call will fail. Similiarly, an API call to retrieve user information will succeed only if the token has user.read scope. You will receive "access denied" error if the scope does not match the API call you are trying to make.

To obtain or refresh an access token, please refer to OAuth2 - Getting Started.

Profile Endpoints

The base URL for the Profile API is:

https://host/profile/v1/

The following production hosts are available:

Data Center Environments Host Description
US Production https://us.api.concursolutions.com -
US Production - access token https://www-us.api.concursolutions.com This is for clients that cannot handle the server request for x.509 cert.
US Implementation https://us-impl.api.concursolutions.com -
EMEA Production https://emea.api.concursolutions.com -
EMEA Production - access token https://www-emea.api.concursolutions.com This is for clients that cannot handle the server request for x.509 cert.
EMEA Implementation https://emea-impl.api.concursolutions.com -
CHINA Production https://cn.api.concurcdc.cn -
CHINA Production - access token https://www-cn.api.concurcdc.cn This is for clients that cannot handle the server request for x.509 cert.

Profile APIs are aware of the US and EMEA data centers. If an API call is made against a specific data center and the target resource is not stored in that data center, you will receive a "301-redirect" that points to the right location for the resource.

Caveats

Changes in Profile do not follow the typical notification or deprecation processes. If you want to be included in the Profile related notifications, please email profile@concur.com.

Travel Profile Resource v1

Deprecation Date: 04/01/2016

Partners and customers using a deprecated API should contact SAP Concur and discuss moving to the latest versions.

Learn more in the API Lifecycle & Deprecation Policy.

Current version: Travel Profile v2

Description

The Travel Profile resource represents a Concur travel profile which contains travel-relation information about a user, such as:

URI

https://{InstanceURL}/api/travelprofile/v1.0/profile

Operations

Get a travel profile

Gets the travel profile information for the specified user. The travel profile includes information such as the user's identity, contact information, rate preferences and discount codes, preferences by travel type, and custom fields. The travel profile information returned by this GET operation depends on whether the caller is a Travel Supplier, a TMC, or a mainstream developer:

Request parameters

All request paramenters are optional. To identify a specific user by login ID or XMLSyncID, you can specify the following request parameters:

Parameter Name Parameter Type Data Type Description
userid_type Path String The type of user identification to use. Possible values are: login and xmlsyncid
userid_value Path String The user's login ID or XMLSync ID, depending on which user type is selected. This parameter must be provided in conjunction with the userid_type parameter.

Headers

Content-Type header

application/xml

Authorization header

Authorization: OAuth {access_token}

Where access_token is the OAuth 2.0 access token of the user whose travel profile information you want to retrieve. If you want to access company-wide travel profile information, the user account associated with the OAuth 2.0 access token must have a Concur account with one of these roles: Web Services Administrator for Professional or Can Administer for Standard.

Data model

The data model of the response for the GET operation.

<ProfileResponse Status="Active|Inactive" Unique="{unique identifier for the user}">
  <General>
    <NamePrefix />
    <FirstName />
    <MiddleName />
    <LastName />
    <NameSuffix />
    <PreferredName />
    <JobTitle />
    <PreferredLanguage />
    <EReceiptOptIn />
    <MarketingOptIn />
    <HasOpenBooking />
    <CountryCode />
    <CompanyName />
  </General>
  <Telephones>
    <Telephone Type="Cell|Other|Pager|Fax|Home|Work|Primary Mobile Phone">
      <ContactOptIn />
      <CountryCode />
      <PhoneNumber />
      <Extension />
    </Telephone>
  </Telephones>
  <Addresses>
    <Address Type="Home|Work|Billing|Other">
      <AttentionLine />
      <Line1 />
      <Line2 />
      <Line3 />
      <MailStop />
      <City />
      <StateProvince />
      <CountryCode />
      <ZipCode />
      <Laditude />
      <Longitude />
    </Address>
  </Addresses>
  <DriversLicenses>
    <DriversLicense>
      <DriversLicenseNumber />
      <IssuingCountry />
      <IssuingState />
      <Expiration />
    </DriversLicense>
  </DriversLicenses>
  <EmailAddresses>
    <EmailAddress />
  </EmailAddresses>
  <RatePreferences>
    <AAARate />
    <AARPRate />
    <GovtRate />
    <MilitaryRate />
  </RatePreferences>
  <DiscountCodes>
    <DiscountCode />
  </DiscountCodes>
  <Air>
    <AirSmokingCode />
    <AirMemberships>
      <AirMembership>
        <VendorCode />
        <AccountNo />
        <Status />
        <StatusBenefits />
        <PointTotal />
        <SegmentTotal />
        <NextStatus />
        <PointsUntilNextStatus />
        <SegmentsUntilNextStatus />
      </AirMembership>
    </AirMemberships>
    <Seat>
      <InterRowPositionCode />
      <SectionPositionCode />
    </Seat>
    <Meals>
      <MealCode />
    </Meals>
    <HomeAirport />
    <AirOther />
    <DHSRedressNumber />
    <DHSKnownTravelerNumber />
  </Air>
  <Car>
    <CarSmokingCode />
    <CarGPS />
    <CarOption />
    <CarMemberships />
    <CarMembership>
      <VendorCode />
      <AccountNo />
      <Status />
      <StatusBenefits />
      <PointTotal />
      <SegmentTotal />
      <NextStatus />
      <PointsUntilNextStatus />
      <SegmentsUntilNextStatus />
    </CarMembership>
    <CarOther />
    <CarSkiRack />
  </Car>
  <Hotel>
    <SmokingCode />
    <HotelMemberships />
    <RoomType />
    <HotelOther />
    <preferFoamPillows />
    <preferCrib />
    <preferRollawayBed />
    <preferGym />
    <preferPool />
    <preferRestaurant />
    <preferWheelchairAccess />
    <preferAccessForBlind />
    <preferRoomService />
    <preferEarlyCheckIn />
  </Hotel>
  <CustomFields>
    <CustomField>
      <Name />
      <Value />
    </CustomField>
  </CustomFields>
</ProfileResponse>

ProfileResponse root element

The ProfileResponse root element contains the General, Telephones, Addresses, DriversLicenses, EmailAddresses, RatePreferences, DiscountCodes, Air, Car, Hotel, and CustomFields child elements. It has the attributes shown in the Data Model section.

General elements

The General parent element contains the following child elements:

Element Name Data Type Description
NamePrefix String The user's name prefix. Format: Varchar(60)
FirstName String The user's first name. Format: Varchar(32)
MiddleName String The user's middle name. Format: Varchar(32)
LastName String The user's last name. Format: Varchar(32)
NameSuffix String The user's name suffix. Format: Varchar(60)
PreferredName String The user's preferred name. Format: Varchar(60)
JobTitle String The user's job title. Format: Nvarchar(255)
PreferredLanguage String The user's preferred language locale. Example: United States English is en-US. Format: Varchar(20)
EReceiptOptIn String Whether the user has opted in to receive e-receipts. Format: True/False
MarketingOptIn String Whether the user has opted in to receive marketing information. Format: True/False
HasOpenBooking Boolean Whether the user has the TripLink User (formerly Open Booking User) permission. Format: True/False
CountryCode String The country code in from the ISO 3166-1 alpha-2 country code specification. Format: Char(2)
CompanyName String The user's company name.

Telephones elements

The Telephones parent element contains a Telephone child element for each included telephone. The Telephone element has the attributes shown in the Response Class section and contains the following child elements:

Element Name Data Type Description
ContactOptIn String Whether the user has opted in to being contacted on this phone. Only appears when the phone type is Cell or Primary Mobile Phone. Format: True/False
CountryCode String The country code in from the ISO 3166-1 alpha-2 country code specification. Format: Char(2)
PhoneNumber String The phone number as entered by the user, which may contain characters such as () or -. Format: Char(60)
NOTE: The user phone number may sometimes be incorrectly parsed if there are data input issues.
Extension String The phone extension. Format: Varchar(60)

Addresses elements

The Addresses parent element contains an Address child element for each included address. The Address element has the attributes shown in the Response Class section and contains the following child elements:

NOTE: The values returned for the Address child elements are as entered by the user. The fields do not enforce formatting and may have a wide variety of values.

Element Name Data Type Description
AttentionLine String Attention Line in the address. Format: Nvarchar(Unlimited)
Line1 String Address line 1. Format: Nvarchar(Unlimited)
Line2 String Address line 2. Format: Nvarchar(Unlimited)
Line3 String Address line 3. Format: Nvarchar(Unlimited)
MailStop String Address mail stop. Format: Nvarchar(Unlimited)
City String The city name. Format: Nvarchar(Unlimited)
StateProvince String The state or province. Format: Nvarchar(Unlimited)
CountryCode String The country code in from the ISO 3166-1 alpha-2 country code specification. Format: Char(2)
ZipCode String The zip code. Format: Varchar(20)
Longitude String Longitude value of Work Address.
Latitude String Latitude value of Work Address.

DriversLicenses elements

The DriversLicenses parent element contains a DriversLicense child element for each each included licenses. The DriversLicense element contains the following child elements:

Element Name Data Type Description
DriversLicenseNumber String The user's driver license identification number. Format: Varchar(30)
IssuingCountry String The country the license was issued in. Format: Char(2)
IssuingState String The state the license was issued in. Format: Varchar(2)
Expiration String The expiration date of the license. Format: YYYY-MM-DD

EmailAddresses elements

The EmailAddresses parent element contains a EmailAddress child element for each included email address. It contains the following child element:

Element Name Data Type Description
EmailAddress String The the user's email address. The EmailAddress element has two attributes: Type and Contact. The Type attribute specifies the type of email address and the possible values are: Business, Business2, Personal. The Contact attribute specifies whether the email address should be used for travel notifications and the possible values are True or False. Format: Varchar(255)

RatePreferences elements

The RatePreferences parent element contains the following child element:

Element Name Data Type Description
AAARate Boolean Whether the user is eligible for the AAA rate. Format: true/false
AARPRate Boolean Whether the user is eligible for the AARP rate. Format: true/false
GovtRate Boolean Whether the user is eligible for the Government rate. Format: true/false
MilitaryRate Boolean Whether the user is eligible for the Military rate. Format: true/false

DiscountCodes elements

The DiscountCodes parent element contains a DiscountCode child element for each included discount code.

Element Name Data Type Description
DiscountCode String The discount code for the specified vendor.The DiscountCode element has a Vendor attribute that specifies the name of the vendor for the discount code.

Air elements

The Air parent element contains the user's air travel preferences and contains the following child elements:

Element Name Data Type Description
AirSmokingCode String Whether the user wants a flight with smoking allowed. Legacy. Format: S, N, D.
AirMemberships Membership The AirMemberships element only appears if the request came from a travel supplier for this travel type, or from a TMC. This element contains an AirMembership child element for each included membership and includes the following child elements:
Seat - This parent element contains the user's Car travel preferences. The Car element contains the following child elements:
Meals - This parent element contains the MealCode child element that indicates the meal preference of the traveler. The possible values are:
AVML = Vegetarian Hindu Meal
BBML = Baby Meal
BLML = Bland Meal
CHML = Child Meal
DBML = Diabetic Meal
FPML = Fruit Platter
GFML = Gluten Intolerant Meal
HNML = Hindu Meal
KSML = Kosher Meal
LCML = Low Calorie Meal
LFML = Low Fat Meal
LSML = Low Salt Meal
MOML = Muslim Meal
NLML = Low Lactose Meal
NSML = No Salt Meal
PFML = Peanut Free Meal
SFML = Seafood Meal
SPML = Special Request Meal
VGML = Vegetarian
RVML = Vegetarian Raw Vegan Meal
VLML = Vegetarian Lacto-Ovo
VJML = Vegetarian Jain Meal
VOML = Vegetarian Oriental Meal

Note: Regular Meal will not return a value for this preference.
HomeAirport String The user's home airport
DHSRedressNumber String TSA Redress Number
DHSKnownTravelerNumber String TSA Known Traveler Number
AirOther String Other Air related description
Air Memberships elements
Element Name Data Type Description
VendorCode String The code for the vendor that manages the loyalty program.
AccountNo String The user's account identifier in the loyalty program.
Status String Name of the user's current level in the loyalty program.
StatusBenefits String Description of a benefit of the loyalty program at the current status.
PointTotal String The user's total number of points in the loyalty program.
SegmentTotal String The user's total segments in the loyalty program.
NextStatus String Name or description of next higher status level in the loyalty program.
PointsUntilNextStatus String Loyalty points required to next status level.
SegmentsUntilNextStatus String Booking segment to next status level.
Seat elements
Element Name Data Type Description
InterRowPositionCode String Preferred position in an airplane row. Format: Window, Aisle, Middle, Isolated, DontCare.
SectionPositionCode String Preference for position in plane. Format: F, B, R, D.

Car elements

The Car parent element contains the user's car travel preferences. It contains the following child elements:

Element Name Data Type Description
CarSmokingCode String Smoking car preferred. Format: S, N, O
CarGPS String Car GPS preference. Format: true/false.
CarOption String Car option preference. Format: Char(3)
CarMemberships Membership The CarMemberships element only appears if the request came from a travel supplier for this travel type, or from a TMC. This element contains a CarMembership child element for each included membership. The CarMembership element has the following child elements:
CarOther String Other Car related description. Format: Char(30)
CarSkiRack String Car ski rack preference. Format: true/false.
Car Memberships elements
Element Name Data Type Description
VendorCode String The code for the vendor that manages the loyalty program.
AccountNo String The user's account identifier in the loyalty program.
Status String Name of the user's current level in the loyalty program.
StatusBenefits String Description of a benefit of the loyalty program at the current status.
PointTotal String The user's total number of points in the loyalty program.
SegmentTotal String The user's total segments in the loyalty program.
NextStatus String Name or description of next higher status level in the loyalty program.
PointsUntilNextStatus String Loyalty points required to next status level.
SegmentsUntilNextStatus String Booking segment to next status level.

Hotel elements

The Hotel parent element contains the user's hotel travel preferences. It contains the following child elements:

Element Name Data Type Description
SmokingCode String Smoking room preference. Format: S, N,D
HotelMemberships - This parent element only appears if the request came from a travel supplier for this travel type, or from a TMC. This element contains a HotelMembership child element for each included membership. The HotelMembership element has the following child elements:
RoomType String Hotel room preference. Values are: H, 2, K, Q, 1, T
HotelOther String Other Hotel related description. Format: Varchar(30)
PreferFoamPillows String Whether the user prefers foam pillows. Format: true/false.
PreferCrib String Whether the user prefers to have a crib. Format:true/false.
PreferRollawayBed String Whether the user prefers to have a rollaway bed. Format:true/false.
PreferGym String Whether the user prefers a hotel with a gym. Format:true/false.
preferPool String Whether the user prefers a hotel with a pool. Format:true/false.
preferRestaraunt String Whether the user prefers a hotel with a restaurant. Format:true/false.
preferWheelchairAccess String Whether the user requires wheelchair access. Format: true/false.
preferAccessForBlind String Whether the user requires a room with access for blind guests. Format:true/false.
preferRoomService String Whether the user prefers a hotel with room service. Format:true/false.
preferEarlyCheckIn String Whether the user prefers a hotel with early check in. Format:true/false.

Hotel Memberships elements

Element Name Data Type Description
VendorCode String The code for the vendor that manages the loyalty program.
AccountNo String The user's account identifier in the loyalty program.
Status String Name of the user's current level in the loyalty program.
StatusBenefits String Description of a benefit of the loyalty program at the current status.
PointTotal String The user's total number of points in the loyalty program.
SegmentTotal String The user's total segments in the loyalty program.
NextStatus String Name or description of next higher status level in the loyalty program.
PointsUntilNextStatus String Loyalty points required to next status level.
SegmentsUntilNextStatus String Booking segment to next status level.

CustomFields elements

The CustomFields parent element contains child elements that specify custom fields in a travel profile. It contains a CustomField child element for each custom field. To retrieve this information, the Travel Profile, Custom Fields scope must be selected in the Register Partner Application page under Web Services.

CustomField child elements

For each custom field, the CustomField element has a Name and Value child element.

Element Name Data Type Description
Name String The name of the custom field. For example, Employee, Cost Centre, Fund, PassportNumber, Visa, and Assistants.
Value String The value of the custom field. If the value is null, the Value child element is omitted.

Examples for Travel Suppliers

Example 1: Get the travel profile for the user associated with the specified OAuth 2.0 access token

Request

GET {InstanceURI}/api/travelprofile/v1.0/profile HTTP/1.1
Authorization: OAuth {access token}

Response

HTTP/1.1 200 OK
Content-Type: application/xml    
<ProfileResponse Status="Active" Unique="CM12345678">
  <General>
    <NamePrefix />
    <FirstName>Maria</FirstName>
    <MiddleName>X</MiddleName>
    <LastName>Black</LastName>
    <NameSuffix />
    <PreferredName />
    <JobTitle>Finance Manager</JobTitle>
    <PreferredLanguage>en-us</PreferredLanguage>
    <EReceiptOptIn>True</EReceiptOptIn>
    <MarketingOptIn>True</MarketingOptIn>
    <HasOpenBooking>true</HasOpenBooking>
    <CountryCode>US</CountryCode>
    <CompanyName>ExampleDotCom</CompanyName>
  </General>
  <Telephones>
    <Telephone Type="Work">
      <CountryCode>001</CountryCode>
      <PhoneNumber>5555551234</PhoneNumber>
      <Extension />
    </Telephone>
    <Telephone Type="Cell">
      <CountryCode>001</CountryCode>
      <PhoneNumber>4155544321</PhoneNumber>
      <Extension />
      <ContactOptIn>True</ContactOptIn>
    </Telephone>
  </Telephones>
  <Addresses>
    <Address Type="Work">
      <AttentionLine>Finance Department</AttentionLine>
      <Line1>1234 Rainy Street.</Line1>
      <Line2>Suite 442</Line2>
      <Line3 />
      <MailStop />
      <City>Seattle</City>
      <StateProvince>WA</StateProvince>
      <CountryCode>US</CountryCode>
      <ZipCode>98102</ZipCode>
      <Longitude>-77.040706000000</Longitude>
      <Latitude>38.812690000000</Latitude>
    </Address>
    <Address Type="Home">
      <AttentionLine />
      <Line1>1234 1st Ave. S</Line1>
      <Line2>Apt. 821</Line2>
      <Line3 />
      <MailStop />
      <City>Seattle</City>
      <StateProvince>WA</StateProvince>
      <CountryCode>US</CountryCode>
      <ZipCode>98102</ZipCode>
      <Longitude>-77.040706000000</Longitude>
      <Latitude>38.812690000000</Latitude>
    </Address>
  </Addresses>
  <DriversLicenses>
    <DriversLicense>
      <DriversLicenseNumber>MIL112233452</DriversLicenseNumber>
      <IssuingCountry>US</IssuingCountry>
      <IssuingState>WA</IssuingState>
      <Expiration>2018-05-22</Expiration>
    </DriversLicense>
  </DriversLicenses>
  <EmailAddresses>
    <EmailAddress Type="Business" Contact="True">mariab@example.com</EmailAddress>
  </EmailAddresses>
  <RatePreferences>
    <AAARate>true</AAARate>
    <AARPRate>false</AARPRate>
    <GovtRate>false</GovtRate>
    <MilitaryRate>false</MilitaryRate>
  </RatePreferences>
  <DiscountCodes>
    <DiscountCode Vendor="Marriott">1234567899</DiscountCode>
  </DiscountCodes>
  <Air>
    <AirSmokingCode>S</AirSmokingCode>
    <AirMemberships>
      <AirMembership>
        <VendorCode>AA</VendorCode>
        <AccountNo>K12345</AccountNo>
        <Status>Normal</Status>
        <StatusBenefits>N/A</StatusBenefits>
        <PointTotal>1234</PointTotal>
        <SegmentTotal>2</SegmentTotal>
        <NextStatus>Super</NextStatus>
        <PointsUntilNextStatus>444</PointsUntilNextStatus>
        <SegmentsUntilNextStatus>2</SegmentsUntilNextStatus>
      </AirMembership>
    </AirMemberships>
    <Seat>
      <InterRowPositionCode>Window</InterRowPositionCode>
      <SectionPositionCode>F</SectionPositionCode>
    </Seat>
    <Meals>
      <MealCode>VGML</MealCode>
    </Meals>
    <HomeAirport>SEA</HomeAirport>
    <AirOther />
  </Air>
  <Car>
    <CarSmokingCode>N</CarSmokingCode>
    <CarGPS>True</CarGPS>
    <CarOption />
    <CarMemberships>
      <CarMembership>
        <VendorCode>ZE</VendorCode>
        <AccountNo>ABCDEF</AccountNo>
        <Status>Newbie</Status>
        <StatusBenefits>10%  discount</StatusBenefits>
        <PointTotal>44</PointTotal>
        <SegmentTotal>8</SegmentTotal>
        <NextStatus>Veteran</NextStatus>
        <PointsUntilNextStatus>55</PointsUntilNextStatus>
        <SegmentsUntilNextStatus>12</SegmentsUntilNextStatus>
      </CarMembership>
      <CarMembership>
        <VendorCode>XW</VendorCode>
        <AccountNo>GHIJK</AccountNo>
        <Status>Gold</Status>
        <StatusBenefits>30%  discount</StatusBenefits>
        <PointTotal>1000</PointTotal>
        <SegmentTotal>50</SegmentTotal>
        <NextStatus>VIP</NextStatus>
        <PointsUntilNextStatus>500</PointsUntilNextStatus>
        <SegmentsUntilNextStatus>25</SegmentsUntilNextStatus>
      </CarMembership>
    </CarMemberships>
    <CarOther />
    <CarSkiRack>False</CarSkiRack>
  </Car>
  <Hotel>
    <SmokingCode>N</SmokingCode>
    <HotelMemberships />
    <RoomType>K</RoomType>
    <HotelOther />
    <PreferFoamPillows>True</PreferFoamPillows>
    <PreferCrib>False</PreferCrib>
    <PreferRollawayBed>True</PreferRollawayBed>
    <PreferGym>True</PreferGym>
    <preferPool>True</preferPool>
    <preferRestaraunt>True</preferRestaraunt>
    <preferWheelchairAccess>False</preferWheelchairAccess>
    <preferAccessForBlind>False</preferAccessForBlind>
    <preferRoomService>True</preferRoomService>
    <preferEarlyCheckIn>False</preferEarlyCheckIn>
  </Hotel>
  <CustomFields>
    <CustomField>
      <Name>Employee ID</Name>
      <Value>12345</Value>
    </CustomField>
    <CustomField>
      <Name>Cost Centre</Name>
      <Value>Headquarters</Value>
    </CustomField>
    <CustomField>
      <Name>Fund</Name>
      <Value>StudentTraining</Value>
    </CustomField>
    <CustomField>
      <Name>Passport Number&gt;</Name>
      <Value>AUS1234</Value>
    </CustomField>
    <CustomField>
      <Name>Visa</Name>
      <Value>EUvisa1234</Value>
    </CustomField>
    <CustomField>
      <Name>Assistants</Name>
      <Value>John Smith</Value>
    </CustomField>
  </CustomFields>
</ProfileResponse>

Example 2: Get the travel profile for a user with a specific login ID

Request

GET https://www.concursolutions.com/api/travelprofile/v1.0/profile?userid_type=login&userid_value=cm@example.com HTTP/1.1
Authorization: OAuth {access token}

Response

The response is the same as in Example 1.

Examples for TMCs

Example 3: Get the travel profile for the user associated with the specified OAuth 2.0 access token

Request

GET {InstanceURI}/api/travelprofile/v1.0/profile HTTP/1.1
Authorization: OAuth {access token}

Response

HTTP/1.1 200 OK
Content-Type: application/xml    
<ProfileResponse Status="Active" Unique="CM12345678">
  <General>
    <NamePrefix />
    <FirstName>Maria</FirstName>
    <MiddleName>X</MiddleName>
    <LastName>Black</LastName>
    <NameSuffix />
    <PreferredName />
    <JobTitle>Finance Manager</JobTitle>
    <PreferredLanguage>en-us</PreferredLanguage>
    <EReceiptOptIn>True</EReceiptOptIn>
    <MarketingOptIn>True</MarketingOptIn>
    <HasOpenBooking>true</HasOpenBooking>
    <CountryCode>US</CountryCode>
    <CompanyName>ExampleDotCom</CompanyName>
  </General>
  <Telephones>
    <Telephone Type="Work">
      <CountryCode>001</CountryCode>
      <PhoneNumber>5555551234</PhoneNumber>
      <Extension />
    </Telephone>
    <Telephone Type="Cell">
      <CountryCode>001</CountryCode>
      <PhoneNumber>4155544321</PhoneNumber>
      <Extension />
      <ContactOptIn>True</ContactOptIn>
    </Telephone>
  </Telephones>
  <Addresses>
    <Address Type="Work">
      <AttentionLine>Finance Department</AttentionLine>
      <Line1>1234 Rainy Street.</Line1>
      <Line2>Suite 442</Line2>
      <Line3 />
      <MailStop />
      <City>Seattle</City>
      <StateProvince>WA</StateProvince>
      <CountryCode>US</CountryCode>
      <ZipCode>98102</ZipCode>
      <Longitude>-77.040706000000</Longitude>
      <Latitude>38.812690000000</Latitude>
    </Address>
    <Address Type="Home">
      <AttentionLine />
      <Line1>1234 1st Ave. S</Line1>
      <Line2>Apt. 821</Line2>
      <Line3 />
      <MailStop />
      <City>Seattle</City>
      <StateProvince>WA</StateProvince>
      <CountryCode>US</CountryCode>
      <ZipCode>98102</ZipCode>
      <Longitude>-77.040706000000</Longitude>
      <Latitude>38.812690000000</Latitude>
    </Address>
  </Addresses>
  <DriversLicenses>
    <DriversLicense>
      <DriversLicenseNumber>MIL112233452</DriversLicenseNumber>
      <IssuingCountry>US</IssuingCountry>
      <IssuingState>WA</IssuingState>
      <Expiration>2018-05-22</Expiration>
    </DriversLicense>
  </DriversLicenses>
  <EmailAddresses>
    <EmailAddress Type="Business" Contact="True">mariab@example.com</EmailAddress>
  </EmailAddresses>
  <RatePreferences>
    <AAARate>true</AAARate>
    <AARPRate>false</AARPRate>
    <GovtRate>false</GovtRate>
    <MilitaryRate>false</MilitaryRate>
  </RatePreferences>
  <DiscountCodes>
    <DiscountCode Vendor="Marriott">1234567899</DiscountCode>
    <DiscountCode Vendor="IHG">111222333</Discount</span>
  </DiscountCodes>
  <Air>
    <AirSmokingCode>S</AirSmokingCode>
    <AirMemberships>
      <AirMembership>
        <VendorCode>AA</VendorCode>
        <AccountNo>K12345</AccountNo>
        <Status>Normal</Status>
        <StatusBenefits>N/A</StatusBenefits>
        <PointTotal>1234</PointTotal>
        <SegmentTotal>2</SegmentTotal>
        <NextStatus>Super</NextStatus>
        <PointsUntilNextStatus>444</PointsUntilNextStatus>
        <SegmentsUntilNextStatus>2</SegmentsUntilNextStatus>
      </AirMembership>
    </AirMemberships>
    <Seat>
      <InterRowPositionCode>Window</InterRowPositionCode>
      <SectionPositionCode>NOPREF</SectionPositionCode>
    </Seat>
    <Meals>
      <MealCode>VGML</MealCode>
    </Meals>
    <HomeAirport>SEA</HomeAirport>
    <AirOther />
  </Air>
  <Car>
    <CarSmokingCode>N</CarSmokingCode>
    <CarGPS>True</CarGPS>
    <CarOption />
    <CarMemberships>
      <CarMembership>
        <VendorCode>ZE</VendorCode>
        <AccountNo>ABCDEF</AccountNo>
        <Status>Newbie</Status>
        <StatusBenefits>10%  discount</StatusBenefits>
        <PointTotal>44</PointTotal>
        <SegmentTotal>8</SegmentTotal>
        <NextStatus>Veteran</NextStatus>
        <PointsUntilNextStatus>55</PointsUntilNextStatus>
        <SegmentsUntilNextStatus>12</SegmentsUntilNextStatus>
      </CarMembership>
      <CarMembership>
        <VendorCode>XW</VendorCode>
        <AccountNo>GHIJK</AccountNo>
        <Status>Gold</Status>
        <StatusBenefits>30%  discount</StatusBenefits>
        <PointTotal>1000</PointTotal>
        <SegmentTotal>50</SegmentTotal>
        <NextStatus>VIP</NextStatus>
        <PointsUntilNextStatus>500</PointsUntilNextStatus>
        <SegmentsUntilNextStatus>25</SegmentsUntilNextStatus>
      </CarMembership>
    </CarMemberships>
    <CarOther />
    <CarSkiRack>False</CarSkiRack>
  </Car>
  <Hotel>
    <SmokingCode>N</SmokingCode>
    <HotelMemberships />
    <RoomType>K</RoomType>
    <HotelOther />
    <PreferFoamPillows>True</PreferFoamPillows>
    <PreferCrib>False</PreferCrib>
    <PreferRollawayBed>True</PreferRollawayBed>
    <PreferGym>True</PreferGym>
    <preferPool>True</preferPool>
    <preferRestaraunt>True</preferRestaraunt>
    <preferWheelchairAccess>False</preferWheelchairAccess>
    <preferAccessForBlind>False</preferAccessForBlind>
    <preferRoomService>True</preferRoomService>
    <preferEarlyCheckIn>False</preferEarlyCheckIn>
  </Hotel>
  <CustomFields>
    <CustomField>
      <Name>Employee ID</Name>
      <Value>12345</Value>
    </CustomField>
    <CustomField>
      <Name>Cost Centre</Name>
      <Value>Headquarters</Value>
    </CustomField>
    <CustomField>
      <Name>Fund</Name>
      <Value>StudentTraining</Value>
    </CustomField>
    <CustomField>
      <Name>Passport Number&gt;</Name>
      <Value>AUS1234</Value>
    </CustomField>
    <CustomField>
      <Name>Visa</Name>
      <Value>EUvisa1234</Value>
    </CustomField>
    <CustomField>
      <Name>Assistants</Name>
      <Value>John Smith</Value>
    </CustomField>
  </CustomFields>
</ProfileResponse>

Example 4: Get the travel profile for a user with a specific login ID

Request

GET https://www.concursolutions.com/api/travelprofile/v1.0/profile?userid_type=login&userid_value=cm@example.com HTTP/1.1
Authorization: OAuth {access token}

Response

The response is the same as in Example 3.

Get a list of travel profile summaries

Gets the list of travel profile summaries that have been updated since the specified date. The response is separated into pages.

Request

GET {InstanceURI}/api/travelprofile/v1.0/profile?LastModifiedDate=2015-01-01T01:00:00 HTTP/1.1
Authorization: OAuth {access token}

Request parameters

All request paramenters are optional. To identify a specific user by login ID or XMLSyncID, you can specify the following request parameters.

Parameter Name|Required/Optional|Parameter Type|Data Type|Description ---|---|---|--- LastModifiedDate|Required|path|string|The date and time, in UTC, that the profiles must be updated after to be included in the response. Format: YYYY-MM-DDThh:mm:ss Page|Optional|path|string|The number of pages to retrieve. If the page is outside the number of existing pages, the response elements will be empty ItemsPerPage|Optional|path|string|The number of travel profiles per page. The maximum value is 200. The default value is 200.

Headers

Accept header

application/xml

Authorization header

Authorization: OAuth {access_token}

Where access_token is the OAuth 2.0 access token of the user whose travel profile summaries you want to retrieve. If you want to access company-wide travel profile information, the user account associated with the OAuth 2.0 access token must have a Concur account with one of these roles: Web Services Administrator for Professional or Can Administer for Standard.

Data model

The data model of the response for the GET operation.

<ConnectResponse>
  <Metadata>
    <Paging>
      <TotalPages />
      <TotalItems />
      <Page />
      <ItemsPerPage />
      <PreviousPageURL />
      <NextPageURL />
    </Paging>
  </Metadata>
  <Data>
    <ProfileSummary>
      <LoginID />
      <XmlProfileSyncID />
      <ProfileLastModifiedUTC />
    </ProfileSummary>
  </Data>
</ConnectResponse>

Response

ConnectResponse root element

The ConnectResponse root element contains the General, Telephones, Addresses, DriversLicenses, EmailAddresses, RatePreferences, DiscountCodes, Air, Car, Hotel, and CustomFields child elements. It has the attributes shown in the Response Class section.

Metadata element

The Metadata parent element contains the Paging child element.

Paging elements

The Paging parent element contains contains the paging information for the response and it contains the following child elements:

Element Name Data Type Description
TotalPages String The total number of pages to return.
TotalItems String The total number of profiles the query returned.
Page String The page number for the set of results in the current response.
ItemsPerPage String The number of items set to display per page.
PreviousPageURL String The URI to the previous page of results. This element will be empty when there are no previous pages.
NextPageURL String The URI to the next set of results. This element will be empty when there are no next pages.

Data element

The Data parent element contains a ProfileSummary child element for each included travel profile.

ProfileSummary

The Paging parent element contains contains the paging information for the response and it contains the following child elements:

Element Name Data Type Description
LoginID String The Concur user login ID.
XMLProfileSyncID String TThe user's XML Profile Sync ID, if available.
ProfileLastModifiedUTC String The date, in UTC, when the travel profile was last modified. Format: YYYY-MM-DDThh:mm:ss.

Example

This example gets the list of travel profile summaries modified after January 1 2015.

Request

GET {InstanceURI}/api/travelprofile/v1.0/profile?LastModifiedDate=2015-01-01T01:00:00 HTTP/1.1
Authorization: OAuth {access token}

Response

HTTP/1.1 200 OK
Content-Type: application/xml
<ConnectResponse>
  <Metadata>
    <Paging>
      <TotalPages>1</TotalPages>
      <TotalItems>2</TotalItems>
      <Page>1</Page>
      <ItemsPerPage>200</ItemsPerPage>
      <PreviousPageURL />
      <NextPageURL />
    </Paging>
  </Metadata>
  <Data>
    <ProfileSummary>
      <LoginID>mariab@company1.com</LoginID>
      <XmlProfileSyncID>string123</XmlProfileSyncID>
      <ProfileLastModifiedUTC>2015-01-01T01:00:00</ProfileLastModifiedUTC>
    </ProfileSummary>
    <ProfileSummary>
      <LoginID>peterk@company1.com</LoginID>
      <XmlProfileSyncID>string456</XmlProfileSyncID>
      <ProfileLastModifiedUTC>2015-01-01T01:00:00</ProfileLastModifiedUTC>
    </ProfileSummary>
  </Data>
</ConnectResponse>

Trip Approval v1

This API has been deprecated.

Retired Date: 10/08/2018

Partners and customers using a deprecated API should contact SAP Concur and discuss moving to the latest versions.

Learn more in the API Lifecycle & Deprecation Policy.

Description

The Trip Approval resource allows clients to approve or reject trips. Clients send the unique identifier for the trip, the approver email and the workflow action to be performed (either approve or reject).

Resource URI

https://www.concursolutions.com/api/tws/v1.0/TripApproval/DoApproval

Supported Content Types

Supported Accept Types

Operations

Update trip approval status

Updates the specified trip as approved or rejected by the supplied approver. Can supply either the ItinLocator or the RecordLocator value.

Request

POST /api/tws/v1.0/TripApproval/DoApproval HTTPS/1.1
Host: www.concursolutions.com
Authorization: OAuth {access token}

Content type

application/xml

Authorization header

The Authorization header must have an OAuth token for a valid Concur trip approver.

Request body elements

The request will contain a TripApprovalRQ parent element with a TransactionId attribute. The TransactionId value is used to identify request and response pairs, and can contain any alphanumeric string that does not contain special characters. The TripApprovalRQ element contains the following child elements:

Element Required? Description
Version Y The version of the web service. Currently 1.0.
ItinLocator N The Itinerary Services Record Locator (also known as Itin Locator or Trip Locator). NOT the GDS record locator. If value of ItinLocator is unknown, RecordLocator element should be passed instead.
RecordLocator Y, if the ItinLocator is not sent The GDS record locator. Should be passed only if the ItinLocator is unknown.
ApproverLogin Y The Travel approver's login ID.
Action Y The workflow action to take. Supported values are approve, reject.

Response

Response body elements

This request will return a TripApprovalRS parent element with a matching TransactionId attribute. The TripApprovalRS element will contain the following child elements:

Element Required? Description
Version Y The version of the web service. Currently 1.0.
ItinLocator N The Itinerary Services Record Locator (also known as Itin Locator or Trip Locator). NOT the GDS record locator. If value of ItinLocator is unknown, RecordLocator element should be passed instead.
RecordLocator Y, if the ItinLocator is not sent The GDS record locator. Should be passed only if the ItinLocator is unknown.
ApproverLogin Y The Travel approver's login ID.
Action Y The workflow action to take. Supported values are approve, reject.

Examples

Example 1: Update a trip as approved with successful response

Request
POST /api/tws/v1.0/TripApproval/DoApproval HTTPS/1.1
Host: www.concursolutions.com
Authorization: OAuth {access token}
Content-Type: application/xml
...

<TripApprovalRQ TransactionId="1cc6ea2d-c711-409e-bb51-63b2bdd485fc">
    <Version>1.0</Version>
    <ItinLocator>CQ-BB8-16JED-3ZW</ItinLocator>
    <ApproverLogin>cm@example.com</ApproverLogin>
    <Action>approve</Action>
</TripApprovalRQ>

Response

HTTPS/1.1 200 OK
Content-Type: application/xml

<TripApprovalRS TransactionId="1cc6ea2d-c711-409e-bb51-63b2bdd485fc">
    <Version>1.0</Version>
    <Status>success</Status>
</TripApprovalRS>

Example 2: Update a trip as approved with error

Request

POST /api/tws/v1.0/TripApproval/DoApproval HTTPS/1.1
Host: www.concursolutions.com
Authorization: OAuth {access token}
Content-Type: application/xml

<TripApprovalRQ TransactionId="1cc6ea2d-c711-409e-bb51-63b2bdd485fc">
    <Version>1.0</Version>
    <ItinLocator>CQ-BB8-16JED-3ZW</ItinLocator>
    <ApproverLogin>cm@example.com</ApproverLogin>
    <Action>approve</Action>
</TripApprovalRQ>

Response

HTTPS/1.1 200 OK
Content-Type: application/xml

<TripApprovalRS TransactionId="1cc6ea2d-c711-409e-bb51-63b2bdd485fc">
    <Version>1.0</Version>
    <Status>failure</Status>
    <Error Code="506">No tripId found for this ItinLocator or RecordLocator.</Error>
</TripApprovalRS>

Error Codes

Code Description
501 TripId or ItinLocator is missing.
503 ManagerId is required. This is sometimes returned when the ApproverLogin is invalid.
504 Action is required.
505 Invalid Action (must be either approve or reject).
506 No tripId found for this ItinLocator or RecordLocator.
507 No request data.
508 Request data is not well formatted XML.
509 XML Validation Error. XML schema validation errors will be supplied, if available.
510 TripLocator or RecordLocator was not found
600 An error occured while approving the trip.
700 An error occured while rejecting the trip.

Custom List Items

Custom list fields are included in many of the web services calls and they require some special consideration.

Value

When posting a list item, the list item code should be sent as the value, not the list item name. The code is returned in the levelxcode element of the Get List Items function.

Posting Connected List Items

There are two types of custom lists: Simple lists and Connected (multi-level) lists. If the list is a connected list, the list fields must be sent in sequential order, from parent to the lowest level child list item, as they are configured in the connected list definition.

Example: If your connected list uses Custom5 for the first level, Custom10 for the second level and Custom2 for the third level, you must send the XML elements for the custom fields in that order:

<Custom5>FirstValueCode</Custom5>  
<Custom10>SecondValueCode</Custom10>  
<Custom2>ThirdValueCode</Custom2>

Common Issues

Developers that post custom list item values can encounter errors when they post a list item that does not exist in the SAP Concur database. This can happen when the list item import hasn't been completed or hasn't run recently. If the posted list item code does not match an existing list item, the post may result in bad data. Use the List Item web service to ensure that the list items you are posting are present in the Concur database.